Skip to content

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

[Metabot] Validate / repair named join field references (#83801)

Sloan Spargerc4b07ccbd17d
diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.clj
index 41b6c061740..f282f915fbb 100644
--- a/src/metabase/agent_lib/representations/repair.clj
+++ b/src/metabase/agent_lib/representations/repair.clj
@@ -2057,15 +2057,22 @@
(resolve/import-table-fk import-resolver source-table-fk))
(catch Exception _ nil)))
+(defn- try-resolve-field-id
+ "Resolve a field target — a portable field FK or a numeric field id — to a numeric field id.
+ Walks JSON-unfolded parent chains via the resolver's `import-field-fk`. Returns nil on failure."
+ [import-resolver field-fk]
+ (try
+ (if (pos-int? field-fk)
+ field-fk
+ (resolve/import-field-fk import-resolver field-fk))
+ (catch Exception _ nil)))
+
(defn- try-resolve-field-target-table-id
"Resolve the target-table-id of a field target — a portable field FK or a numeric field id —
- by looking up the field and following its `:table-id`. Walks JSON-unfolded parent chains via
- the resolver's `import-field-fk`. Returns nil on failure."
+ by looking up the field and following its `:table-id`. Returns nil on failure."
[mp import-resolver field-fk]
(try
- (when-let [fid (if (pos-int? field-fk)
- field-fk
- (resolve/import-field-fk import-resolver field-fk))]
+ (when-let [fid (try-resolve-field-id import-resolver field-fk)]
(:table-id (lib.metadata.protocols/field mp fid)))
(catch Exception _ nil)))
@@ -2384,9 +2391,16 @@
;;; is cached, and we only do this for queries that actually have multiple stages.
;;; ============================================================
-(defn- string-cross-stage-field-clause? [v]
+(defn- stage-join-aliases [stage]
+ (into #{} (keep #(when (map? %) (get % "alias"))) (get stage "joins")))
+
+(defn- string-cross-stage-field-clause?
+ "True if `v` is a string-named field ref to a previous-stage column of a stage whose joins are
+ aliased `join-aliases`. A ref through one of those aliases names a join's column instead."
+ [join-aliases v]
(and (not (map-entry? v))
- (match/matches? v (:and ["field" (_ :guard map?) (_ :guard non-blank-string?)]))))
+ (match/matches? v (:and ["field" (_ :guard map?) (_ :guard non-blank-string?)]))
+ (not (contains? join-aliases (get (nth v 1) "join-alias")))))
(defn- types-from-column
"Pull `\"base-type\"` (and optionally `\"effective-type\"`) off a `lib/returned-columns`
@@ -2402,37 +2416,39 @@
(defn- column-descriptors
"Build the cross-stage match oracle from a `lib/returned-columns` sequence: a vector of
- `{:name <machine-name>, :display-name <display-name>, :types {\"base-type\" …}|nil}`
+ `{:name <machine-name>, :display-name <display-name>, :id <field-id>|nil, :types {\"base-type\" …}|nil}`
descriptors. `:types` is nil when the column exposes no usable `base-type`. Carrying the
- `:display-name` lets [[match-cross-stage-column]] recover a ref the LLM wrote with the UI
- label (e.g. `\"Max of Instance Has SC\"`) instead of the machine name (`max`)."
+ `:display-name` lets [[match-cross-stage-column]] recover a ref the LLM wrote with the UI label
+ (e.g. `\"Max of Instance Has SC\"`) instead of the machine name (`max`)."
[cols]
(mapv (fn [col]
{:name (:name col)
:display-name (:display-name col)
+ :id (:id col)
:types (types-from-column col)})
cols))
-(defn- mini-resolved-columns
- "Resolve `stages[0..idx-1]` as a self-contained query, run it through `lib/query`, and return
- the prefix's returned columns as a vector of [[column-descriptors]].
-
- Returns `nil` (logged at debug) if anything in the resolve / lib/query path throws. The
- enclosing pass treats `nil` as 'skip this stage's repairs and let downstream surface the real
- error'."
- [mp query stage-idx content-store]
+(defn- resolved-columns
+ "Resolve `stages` as a standalone query against `database` and return their returned columns as
+ a vector of [[column-descriptors]], or nil when anything in the resolve path throws. `what`
+ names the stages in the debug log."
+ [mp database stages content-store what]
(try
- (let [prefix-stages (subvec (get query "stages") 0 stage-idx)
- prefix-query (assoc query "stages" prefix-stages)
- resolved (repr.resolve/resolve-query mp prefix-query content-store)
- lib-q (lib/query mp resolved)
- cols (lib/returned-columns lib-q)]
- (column-descriptors cols))
+ (let [query (cond-> {"lib/type" "mbql/query" "stages" stages}
+ database (assoc "database" database))
+ resolved (repr.resolve/resolve-query mp query content-store)]
+ (column-descriptors (lib/returned-columns (lib/query mp resolved))))
(catch Exception e
- (log/debugf "[repr-repair] mini-resolve of stages[0..%d] failed; skipping cross-stage type inference for stage %d: %s"
- (dec stage-idx) stage-idx (ex-message e))
+ (log/debugf "[repr-repair] resolve of %s failed; skipping field-type inference: %s" what (ex-message e))
nil)))
+(defn- mini-resolved-columns
+ "The [[resolved-columns]] of the stages before `stage-idx`: the columns that stage can reference.
+ `nil` means 'skip this stage's repairs and let downstream surface the real error'."
+ [mp query stage-idx content-store]
+ (resolved-columns mp (get query "database") (subvec (get query "stages") 0 stage-idx) content-store
+ (format "stages[0..%d] (prefix of stage %d)" (dec stage-idx) stage-idx)))
+
(defn- strip-surrounding-double-quotes
"If `s` is wrapped in a matched pair of leading/trailing double-quote characters, return the
inner string; otherwise return `s` unchanged.
@@ -2517,14 +2533,15 @@
resolution context (the join's own `stages`) and shouldn't reach into their parent stage's
previous-stage columns."
[stage cols]
- (let [joins (get stage "joins")
- stage' (cond-> stage (contains? stage "joins") (dissoc "joins"))
- walked (walk/postwalk
- (fn [node]
- (if (string-cross-stage-field-clause? node)
- (maybe-fill-cross-stage-types node cols)
- node))
- stage')]
+ (let [joins (get stage "joins")
+ aliases (stage-join-aliases stage)
+ stage' (cond-> stage (contains? stage "joins") (dissoc "joins"))
+ walked (walk/postwalk
+ (fn [node]
+ (if (string-cross-stage-field-clause? aliases node)
+ (maybe-fill-cross-stage-types node cols)
+ node))
+ stage')]
(cond-> walked
(contains? stage "joins") (assoc "joins" joins))))
@@ -2539,22 +2556,11 @@
Returns `nil` if anything in the resolve path throws - the resolver will surface the real
error on the main pipeline. Logged at debug."
[mp query stage-idx content-store]
- (let [stage (get-in query ["stages" stage-idx])]
- (when-let [source-card (get stage "source-card")]
- (try
- (let [bare-stage {"lib/type" "mbql.stage/mbql"
- "source-card" source-card}
- bare-query {"lib/type" "mbql/query"
- "database" (get query "database")
- "stages" [bare-stage]}
- resolved (repr.resolve/resolve-query mp bare-query content-store)
- lib-q (lib/query mp resolved)
- cols (lib/returned-columns lib-q)]
- (column-descriptors cols))
- (catch Exception e
- (log/debugf "[repr-repair] source-card resolve of stage %d failed; skipping field-type inference: %s"
- stage-idx (ex-message e))
- nil)))))
+ (when-let [source-card (get-in query ["stages" stage-idx "source-card"])]
+ (let [bare-stage {"lib/type" "mbql.stage/mbql"
+ "source-card" source-card}]
+ (resolved-columns mp (get query "database") [bare-stage] content-store
+ (format "the source-card of stage %d" stage-idx)))))
(defn- infer-source-card-field-types*
"Stamp `base-type` / `effective-type` onto `[field, opts, \"<col>\"]` clauses in any stage
@@ -2580,6 +2586,167 @@
q)]
(recur (inc i) q')))))))
+;;; ============================================================
+;;; Pass 4.7 -- type and check join-alias field references
+;;;
+;;; A join-alias field ref names a column returned by a join on the same stage. The string-named
+;;; form needs `base-type` like the cross-stage refs above, but Pass 5 skips it: a join's columns
+;;; are not the previous stage's. Each referenced join's own stages are resolved as a standalone
+;;; query, and its returned columns both type the string refs and check every join-alias ref
+;;; against what the join actually returns. A concrete-column ref to a column a grouped join
+;;; doesn't return, or a string ref the LLM typed itself with a name the join doesn't return,
+;;; passes lib and only fails in SQL, so both are caught here too. A ref whose alias
+;;; names no join on its stage is a previous-stage ref, typed and checked by Passes 4.5 / 5 / 5.7;
+;;; refs whose join or field can't be resolved are left for the resolver to report.
+;;; ============================================================
+
+(defn- join-alias-string-field-clause? [v]
+ (and (not (map-entry? v))
+ (match/matches? v ["field"
+ {"join-alias" (_ :guard non-blank-string?)}
+ (_ :guard non-blank-string?)])))
+
+(defn- join-alias-path-field-clause?
+ "True if `v` is a concrete-column field ref (portable path or numeric id) through an explicit
+ join, other than an implicit join hop from the joined table."
+ [v]
+ (and (field-clause? v)
+ (non-blank-string? (get (nth v 1) "join-alias"))
+ (not (contains? (nth v 1) "source-field"))))
+
+(defn- plain-table-join?
+ "True when `join` is a single stage over a table that neither groups nor narrows its columns, so
+ every column of that table can be referenced through the join."
+ [join]
+ (let [stages (get join "stages")]
+ (and (vector? stages)
+ (= 1 (count stages))
+ (map? (first stages))
+ (contains? (first stages) "source-table")
+ (not-any? #(contains? (first stages) %) ["aggregation" "breakout" "fields"]))))
+
+(defn- without-join-stages
+ "`stage` with each join's own `stages` removed, leaving the clauses that may reference a join's
+ columns: the stage's own and the joins' `conditions`."
+ [stage]
+ (cond-> stage
+ (sequential? (get stage "joins"))
+ (update "joins" (partial mapv #(cond-> % (map? %) (dissoc "stages"))))))
+
+(defn- postwalk-outside-join-stages
+ "`walk/postwalk` `f` over the parts of `stage` that [[without-join-stages]] keeps."
+ [f stage]
+ (let [joins (get stage "joins")]
+ (cond-> (walk/postwalk f (without-join-stages stage))
+ (sequential? joins)
+ (update "joins" #(mapv (fn [walked join]
+ (cond-> walked
+ (and (map? join) (contains? join "stages")) (assoc "stages" (get join "stages"))))
+ %
+ joins)))))
+
+(defn- join-alias-refs
+ "`stage`'s join-alias string refs (`:named`) and concrete-column join-alias refs (`:path`), each
+ grouped by alias, outside the joins' own `stages`."
+ [stage]
+ (let [stage' (without-join-stages stage)
+ alias #(get (nth % 1) "join-alias")]
+ {:named (group-by alias (match/match-many stage' (node :guard (join-alias-string-field-clause? node)) node))
+ :path (group-by alias (match/match-many stage' (node :guard (join-alias-path-field-clause? node)) node))}))
+
+(defn- bad-join-alias-refs
+ "The distinct `named-refs` naming no column in `cols`, followed by the distinct `path-refs` whose
+ field matches no column of `cols` by id, or by name among the columns without an id. A path ref
+ whose field can't be resolved is skipped."
+ [mp cols named-refs path-refs import-resolver]
+ (let [returned-ids (set (keep :id cols))
+ id-less-names (set (keep #(when-not (:id %) (:name %)) cols))]
+ (distinct
+ (concat
+ (filter #(nil? (match-cross-stage-column cols (nth % 2))) named-refs)
+ (filter #(when-let [field (some->> (try-resolve-field-id @import-resolver (nth % 2))
+ (lib.metadata.protocols/field mp))]
+ ;; like lib, fall back to the field's name only for a column without an id, e.g.
+ ;; one returned through a native card
+ (and (not (contains? returned-ids (:id field)))
+ (not (contains? id-less-names (:name field)))))
+ path-refs)))))
+
+(defn- field-target-name
+ "The column a field ref's target denotes: the name itself, or `TABLE.FIELD` for a portable path
+ or a numeric field id, so a column isn't mistaken for another table's column of the same name."
+ [mp target]
+ (cond
+ (string? target) target
+ (vector? target) (str/join "." (drop 2 target))
+ (pos-int? target) (let [field (lib.metadata.protocols/field mp target)]
+ (str (:name (lib.metadata.protocols/table mp (:table-id field))) "." (:name field)))))
+
+(defn- repair-join-alias-refs-in-stage
+ "Type `stage`'s join-alias string refs. Returns `{:stage <typed stage>, :problems [...]}`, one
+ problem per join that has refs naming columns it doesn't return."
+ [query mp content-store import-resolver idx stage]
+ (let [{:keys [named path]} (join-alias-refs stage)
+ checks (vec (for [join (when (or (seq named) (seq path)) (get stage "joins"))
+ :let [alias (when (map? join) (get join "alias"))
+ named-refs (get named alias)
+ path-refs (when-not (plain-table-join? join) (get path alias))]
+ :when (or named-refs path-refs)
+ :let [cols (when (vector? (get join "stages"))
+ (resolved-columns mp (get query "database") (get join "stages") content-store
+ (format "join %s" (pr-str alias))))]
+ :when cols]
+ {:alias alias :cols cols :named-refs named-refs :path-refs path-refs}))
+ alias->cols (into {} (map (juxt :alias :cols)) checks)]
+ {:stage (cond->> stage
+ (seq alias->cols)
+ (postwalk-outside-join-stages
+ (fn [node]
+ (if-let [cols (and (join-alias-string-field-clause? node)
+ (alias->cols (get (nth node 1) "join-alias")))]
+ (maybe-fill-cross-stage-types node cols)
+ node))))
+ :problems (vec (for [{:keys [alias cols named-refs path-refs]} checks
+ :let [bad (bad-join-alias-refs mp cols named-refs path-refs import-resolver)]
+ :when (seq bad)]
+ {:stage idx
+ :join-alias alias
+ :clauses (vec bad)
+ :columns (vec (distinct (map #(field-target-name mp (nth % 2)) bad)))
+ :available (mapv :name cols)}))}))
+
+(defn- unresolved-join-alias-fields-error
+ [problems]
+ (ex-info
+ (tru "Some join column references name a column their join doesn''t return: {0}. Reference a join column by its machine name (e.g. an aggregation is `min`, `count`, `sum` - never its display label like `Min of X`), and only columns the join returns: a grouped join returns just its breakouts and aggregations."
+ (str/join "; " (for [{:keys [stage join-alias columns available]} problems]
+ (tru "stage {0}, join {1} doesn''t return {2} (available: {3})"
+ stage
+ (pr-str join-alias)
+ (str/join ", " (map pr-str columns))
+ (str/join ", " available)))))
+ {:agent-error? true
+ :error :unresolved-join-alias-field
+ :problems problems}))
+
+(defn- repair-join-alias-refs*
+ "Pass 4.7: type the join-alias string field refs of every stage from the referenced joins'
+ returned columns, and raise one `:agent-error?` listing every join-alias ref, across all stages,
+ that names a column its join doesn't return. Only joins named by a string ref, or by a
+ concrete-column ref into a join that isn't a [[plain-table-join?]], are resolved."
+ [query mp content-store]
+ (if-not (and mp (map? query) (vector? (get query "stages")))
+ query
+ (let [import-resolver (delay (resolve.mp/import-resolver mp content-store))
+ results (into [] (map-indexed (fn [idx stage]
+ (if (map? stage)
+ (repair-join-alias-refs-in-stage query mp content-store import-resolver idx stage)
+ {:stage stage})))
+ (get query "stages"))]
+ (when-let [problems (seq (mapcat :problems results))]
+ (throw (unresolved-join-alias-fields-error (vec problems))))
+ (assoc query "stages" (mapv :stage results)))))
+
(defn- infer-cross-stage-field-types*
"Top-level cross-stage field-type inference pass. No-op when the query has fewer than two
stages or `mp` is nil."
@@ -2617,8 +2784,8 @@
(defn- unstamped-cross-stage-ref?
"True if `node` is a `[\"field\" {} \"<name>\"]` cross-stage/source-card ref still lacking
`base-type` (an LLM-authored `base-type` is left for the resolver / schema to judge)."
- [node]
- (and (string-cross-stage-field-clause? node)
+ [join-aliases node]
+ (and (string-cross-stage-field-clause? join-aliases node)
(not (contains? (nth node 1) "base-type"))))
(defn- stage-has-unstamped-cross-stage-ref?
@@ -2626,17 +2793,19 @@
its `joins` subtrees? Lets the assert pass skip the (resolving) confirmation step entirely
on the happy path, where every ref already carries a stamped `base-type`."
[stage]
- (let [stage' (cond-> stage (contains? stage "joins") (dissoc "joins"))]
+ (let [aliases (stage-join-aliases stage)
+ stage' (cond-> stage (contains? stage "joins") (dissoc "joins"))]
(some? (match/match-one stage'
- (_ :guard unstamped-cross-stage-ref?) true))))
+ (node :guard (unstamped-cross-stage-ref? aliases node)) true))))
(defn- first-unresolved-cross-stage-ref
"Return the first [[unstamped-cross-stage-ref?]] clause in `stage` that matches no column in
`cols`, or nil. Skips `joins` subtrees (their own resolution context)."
[stage cols]
- (let [stage' (cond-> stage (contains? stage "joins") (dissoc "joins"))]
+ (let [aliases (stage-join-aliases stage)
+ stage' (cond-> stage (contains? stage "joins") (dissoc "joins"))]
(match/match-one stage'
- (node :guard (and (unstamped-cross-stage-ref? node)
+ (node :guard (and (unstamped-cross-stage-ref? aliases node)
(nil? (match-cross-stage-column cols (nth node 2)))))
node)))
@@ -2986,13 +3155,17 @@
a `source-card` stage, this relies on Pass 4.5 having already typed that stage's own
field refs - otherwise the prefix fails to resolve/schema-validate and the mini-resolve
silently no-ops (BOT-1604).
+ 4.7. infer `base-type` / `effective-type` on join-alias string field references from the
+ referenced join's own resolved returned columns, and raise an `:agent-error?` for a
+ join-alias ref naming a column its join doesn't return. Runs before Pass 5 so a stage
+ carrying such a ref can still be mini-resolved as a prefix.
5.7. assert that every string-named cross-stage / source-card field ref resolved to a real
column (i.e. Pass 4.5 / 5 stamped its `base-type`). A ref that matched nothing is the
LLM naming a column that doesn't exist (often a display label); raise an `:agent-error?`
naming it and listing the valid columns, instead of letting it pass through into a
schema-invalid, non-runnable query (BOT-1442).
- Pass 4, Pass 4.5, Pass 5, and Pass 5.7 require `mp` (a `MetadataProvider`); they are
+ Pass 4, Pass 4.5, Pass 4.7, Pass 5, and Pass 5.7 require `mp` (a `MetadataProvider`); they are
best-effort no-ops when `mp` can't resolve the relevant pieces (so the subsequent
validate/resolve stages can surface the real error with their own, better messages). Hard FK
errors from Pass 4 (`:no-fk-path`, `:ambiguous-fk`) are raised as `:agent-error?` ex-info so
@@ -3030,6 +3203,7 @@
(resolve-source-field-join-alias* mp content-store)
(resolve-implicit-joins* mp content-store)
(infer-source-card-field-types* mp content-store)
+ (repair-join-alias-refs* mp content-store)
(infer-cross-stage-field-types* mp content-store)
(assert-cross-stage-refs-resolved* mp content-store)
friendly-errors*)))
diff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.clj
index 626d9c739e7..d28152411f2 100644
--- a/src/metabase/metabot/tools/construct.clj
+++ b/src/metabase/metabot/tools/construct.clj
@@ -1,6 +1,7 @@
(ns metabase.metabot.tools.construct
"Notebook query construction tool wrappers."
(:require
+ [clojure.string :as str]
[malli.error :as me]
[malli.util :as mut]
[metabase.agent-lib.representations :as repr]
@@ -663,13 +664,45 @@
(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
+ to Malli's own message. Missing keys the LLM never writes itself are translated into their usual
+ cause instead of being named."
+ [error]
+ (let [missing (when (= :malli.core/missing-key (:type error)) (peek (:in error)))]
+ (cond
+ ;; normalization stamps `:lib/uuid` on every clause; one missing means normalizing a clause
+ ;; inside it failed, often because it references something that doesn't exist
+ (= :lib/uuid missing)
+ (tru "a reference inside it could not be resolved - often a field reference to a column, join alias, or expression that does not exist. Refer to a join''s or an earlier stage''s columns by their exact machine name (an aggregation is `min`, `count`, `sum`)")
+
+ (= :base-type missing)
+ (tru "a field reference by name is missing `base-type`, usually because the name matches no real column")
+
+ missing
+ (tru "missing `{0}`" (name missing))
+
+ ;; the message of `::lib.schema.expression/expression.definition`'s aggregation check
+ (= "non-aggregation expression" (me/error-message error))
+ (tru "{0}: aggregation and window functions such as `offset` cannot be custom columns - move them to `aggregation:` or `order-by:`" (me/error-message error)))))
+
(defn- query-not-runnable-explanation
- "When `pmbql-query` would make the FE's `canRun` gate return false, return a humanized Malli
- explanation of why; nil when the query is runnable."
+ "When `pmbql-query` would make the FE's `canRun` gate return false, return an LLM-facing
+ description of where and why; nil when the query is runnable. Problems [[not-runnable-problem]]
+ explains are listed first, and the usual causes are added when it explains none."
[pmbql-query]
(binding [lib.schema.expression/*suppress-expression-type-check?* true]
(when-let [explanation (mr/explain :metabase.lib.schema/query pmbql-query)]
- (me/humanize explanation))))
+ (let [errors (sort-by (comp nil? not-runnable-problem) (:errors explanation))]
+ (cond-> (or (some->> errors
+ (map #(str (pr-str (:in %)) ": " (or (not-runnable-problem %) (me/error-message %))))
+ distinct
+ (take 3)
+ seq
+ (str/join "; "))
+ (tru "the query does not match the query builder''s schema"))
+ (not-any? not-runnable-problem errors)
+ (str ". " (tru "This usually means a field reference is missing its type or names a column that does not exist, or an aggregation or window function such as `offset` is in `expressions:` instead of `aggregation:` or `order-by:`")))))))
(defn- execute-representations-query*
"Execute a notebook query in the canonical portable MBQL 5 representations format.
@@ -751,8 +784,8 @@
_validated (repr/validate-query repaired)
pmbql-query (repr.resolve/resolve-query mp repaired permission-aware-content-store)
_runnable (when-let [why (query-not-runnable-explanation pmbql-query)]
- (throw (ex-info (tru "The constructed query is not runnable - it would fail the query builder''s validation, so it cannot be visualized or saved. This usually means a field reference is missing its type or names a column that does not exist, or an aggregation/window function (e.g. `offset`) was placed in `expressions:` (custom columns) where it is not allowed - move it to `aggregation:` or `order-by:`. Schema validation details: {0}"
- (pr-str why))
+ (throw (ex-info (tru "The constructed query is not runnable - it would fail the query builder''s validation, so it cannot be visualized or saved. Problem in {0}."
+ why)
{:agent-error? true
:error :query-not-runnable
:status-code 400})))
diff --git a/test/metabase/agent_lib/representations/repair_test.clj b/test/metabase/agent_lib/representations/repair_test.clj
index d7773381c76..58ec1123674 100644
--- a/test/metabase/agent_lib/representations/repair_test.clj
+++ b/test/metabase/agent_lib/representations/repair_test.clj
@@ -7,8 +7,12 @@
[clojure.test.check.properties :as prop]
[metabase.agent-lib.representations :as repr]
[metabase.agent-lib.representations.repair :as repair]
+ [metabase.agent-lib.representations.resolve :as repr.resolve]
[metabase.lib-be.core :as lib-be]
[metabase.lib.test-util :as lib.tu]
+ [metabase.models.serialization.resolve :as serdes.resolve]
+ [metabase.models.serialization.resolve.mp :as resolve.mp]
+ [metabase.test :as mt]
[metabase.util.date-2 :as u.date]))
(set! *warn-on-reflection* true)
@@ -3491,3 +3495,273 @@
(let [bug ["contains" {} ["field" {} ["S" "P" "T" "C"]] "x" {"case-sensitive" false}]
once (repair/repair trivial-mp bug)]
(is (= once (repair/repair trivial-mp once))))))
+
+;;; ============================================================
+;;; Pass 4.7 - join-alias field refs (BOT-2222)
+;;; ============================================================
+
+(def ^:private first-orders-card-eid "aBc123_456DefGhI789_K")
+(def ^:private native-orders-card-eid "nAt123_456DefGhI789_K")
+
+(def ^:private mp-orders-with-cards
+ "ORDERS, PEOPLE (whose `ID` shares its name with ORDERS'), an MBQL card returning each user's first
+ order date (`USER_ID`, `min`), and a native card returning `USER_ID` and `CREATED_AT` without field
+ ids."
+ (lib.tu/mock-metadata-provider
+ {:database {:id 1 :name "Sample"}
+ :tables [{:id 10 :name "ORDERS" :schema "PUBLIC" :db-id 1}
+ {:id 20 :name "PEOPLE" :schema "PUBLIC" :db-id 1}]
+ :fields [{:id 100 :name "ID" :table-id 10 :base-type :type/Integer}
+ {:id 101 :name "TOTAL" :table-id 10 :base-type :type/Float}
+ {:id 102 :name "USER_ID" :table-id 10 :base-type :type/Integer}
+ {:id 103 :name "CREATED_AT" :table-id 10 :base-type :type/Date}
+ {:id 200 :name "ID" :table-id 20 :base-type :type/Integer}]
+ :cards [{:id 500
+ :name "First orders"
+ :database-id 1
+ :type :question
+ :entity-id first-orders-card-eid
+ :dataset-query {:lib/type :mbql/query
+ :database 1
+ :stages [{:lib/type :mbql.stage/mbql :source-table 10}]}
+ :result-metadata [{:name "USER_ID" :id 102 :base-type :type/Integer}
+ {:name "min" :base-type :type/Date}]}
+ {:id 501
+ :name "Native first orders"
+ :database-id 1
+ :type :question
+ :entity-id native-orders-card-eid
+ :dataset-query {:lib/type :mbql/query
+ :database 1
+ :stages [{:lib/type :mbql.stage/native :native "SELECT 1"}]}
+ :result-metadata [{:name "USER_ID" :base-type :type/Integer}
+ {:name "CREATED_AT" :base-type :type/Date}]}]}))
+
+(def ^:private card-content-store
+ (let [cards [{:id 500 :database_id 1 :entity_id first-orders-card-eid}
+ {:id 501 :database_id 1 :entity_id native-orders-card-eid}]]
+ (reify resolve.mp/ContentStore
+ (card-by-entity-id [_ eid] (some #(when (= eid (:entity_id %)) %) cards))
+ (measure-by-entity-id [_ _] nil)
+ (segment-by-entity-id [_ _] nil)
+ (card-by-id [_ id] (some #(when (= id (:id %)) %) cards))
+ (measure-by-id [_ _] nil)
+ (segment-by-id [_ _] nil))))
+
+(def ^:private orders ["Sample" "PUBLIC" "ORDERS"])
+
+(defn- orders-col [column] ["field" {} (conj orders column)])
+
+(defn- join-ref [alias target] ["field" {"join-alias" alias} target])
+
+(defn- typed [field-ref type-name] (assoc-in field-ref [1 "base-type"] type-name))
+
+(defn- stage [m] (merge {"lib/type" "mbql.stage/mbql"} m))
+
+(defn- orders-stage [m] (stage (merge {"source-table" orders} m)))
+
+(def ^:private first-orders-stage
+ "Each user's first order date: returns `USER_ID` and `min`."
+ (orders-stage {"aggregation" [["min" {} (orders-col "CREATED_AT")]]
+ "breakout" [(orders-col "USER_ID")]}))
+
+(defn- join
+ "A left join over `stages`, on `lhs` (default ORDERS.USER_ID) = the join's `USER_ID` by path."
+ [alias stages & {:keys [lhs] :or {lhs (orders-col "USER_ID")}}]
+ {"alias" alias
+ "strategy" "left-join"
+ "stages" stages
+ "conditions" [["=" {} lhs (join-ref alias (conj orders "USER_ID"))]]})
+
+(defn- query [& stages] {"lib/type" "mbql/query" "database" "Sample" "stages" (vec stages)})
+
+(defn- repair* [q] (repair/repair mp-orders-with-cards q card-content-store))
+
+(defn- repair-error
+ "The ex-data of the error `q`'s repair raises, plus its `:message`; nil when repair succeeds."
+ [q]
+ (try (repair* q) nil
+ (catch clojure.lang.ExceptionInfo e (assoc (ex-data e) :message (ex-message e)))))
+
+(defn- join-problems
+ "`[stage join-alias columns]` per problem in the join-alias error `q`'s repair raises, or nil."
+ [q]
+ (let [e (repair-error q)]
+ (when (= :unresolved-join-alias-field (:error e))
+ (mapv (juxt :stage :join-alias :columns) (:problems e)))))
+
+(defn- base-type [field-ref] (get-in field-ref [1 "base-type"]))
+
+(def ^:private first-order-query
+ "Refs `First`'s `min` by name from every clause that can carry one."
+ (let [min-ref (join-ref "First" "min")]
+ (query (orders-stage {"joins" [(join "First" [first-orders-stage])]
+ "expressions" [["=" {"lib/expression-name" "First order?"} (orders-col "CREATED_AT") min-ref]]
+ "breakout" [min-ref]
+ "aggregation" [["max" {} min-ref]]
+ "filters" [["not-null" {} min-ref]]
+ "order-by" [["asc" {} min-ref]]}))))
+
+(deftest ^:parallel join-alias-field-type-happy-path-test
+ (let [decoy-stages [(orders-stage {"filters" [["not-null" {} (join-ref "First" "min")]]})]
+ q (-> first-order-query
+ (assoc-in ["stages" 0 "joins" 0 "conditions" 0 3] (join-ref "First" "USER_ID"))
+ (update-in ["stages" 0 "joins"] conj (join "Decoy" decoy-stages)))
+ out (get-in (repair* q) ["stages" 0])]
+ (doseq [path [["expressions" 0 3] ["breakout" 0] ["aggregation" 0 2] ["filters" 0 2] ["order-by" 0 2]]]
+ (testing (str "the ref in " (first path) " is typed from the join")
+ (is (= ["field" {"join-alias" "First" "base-type" "type/Date" "effective-type" "type/Date"} "min"]
+ (get-in out path)))))
+ (testing "a by-name ref in the join's conditions is typed"
+ (is (= "type/Integer" (base-type (get-in out ["joins" 0 "conditions" 0 3])))))
+ (testing "a ref with the same alias inside a join's own stages is left alone"
+ (is (= decoy-stages (get-in out ["joins" 1 "stages"]))))))
+
+(deftest ^:parallel join-alias-field-type-recovers-display-name-test
+ (let [q (query (orders-stage {"joins" [(join "First" [first-orders-stage])]
+ "filters" [["not-null" {} (join-ref "First" "Min of Created At")]]}))]
+ (is (= ["field" {"join-alias" "First" "base-type" "type/Date" "effective-type" "type/Date"} "min"]
+ (get-in (repair* q) ["stages" 0 "filters" 0 2])))))
+
+(deftest ^:parallel join-alias-field-type-source-card-join-test
+ (let [q (query (orders-stage {"joins" [(join "Card" [(stage {"source-card" first-orders-card-eid})])]
+ "filters" [["not-null" {} (join-ref "Card" "min")]]}))]
+ (is (= "type/Date" (base-type (get-in (repair* q) ["stages" 0 "filters" 0 2]))))))
+
+(def ^:private min-total-by-user-stage
+ "Returns `USER_ID` and a Float `min`, which a Date `min` from a join must not be confused with."
+ (orders-stage {"aggregation" [["min" {} (orders-col "TOTAL")]]
+ "breakout" [(orders-col "USER_ID")]}))
+
+(def ^:private user-id-by-name (typed ["field" {} "USER_ID"] "type/Integer"))
+
+(deftest ^:parallel join-alias-field-type-scoped-to-the-stage-with-the-join-test
+ (let [joined-here (query min-total-by-user-stage
+ (stage {"joins" [(join "First" [first-orders-stage] :lhs user-id-by-name)]
+ "filters" [["not-null" {} (join-ref "First" "min")]]}))
+ joined-before (fn [column]
+ (query (orders-stage {"joins" [(assoc (join "First" [first-orders-stage]) "fields" "all")]})
+ (stage {"filters" [["not-null" {} (join-ref "First" column)]]})))]
+ (testing "a ref through a join on its own stage is typed from that join, not the previous stage's same-named column"
+ (is (= "type/Date" (base-type (get-in (repair* joined-here) ["stages" 1 "filters" 0 2])))))
+ (testing "a ref through an alias no join on its stage has is typed from the previous stage"
+ (is (= "type/Date" (base-type (get-in (repair* (joined-before "min")) ["stages" 1 "filters" 0 2])))))
+ (testing "a bad name through an alias no join on its stage has raises the cross-stage error, not the join error"
+ (is (= :unresolved-cross-stage-field (:error (repair-error (joined-before "nope"))))))))
+
+(deftest ^:parallel join-alias-field-type-unresolvable-join-is-skipped-test
+ (let [min-ref (join-ref "Broken" "min")
+ q (query min-total-by-user-stage
+ (stage {"joins" [(join "Broken" [(stage {"source-table" ["Sample" "PUBLIC" "NOPE"]})]
+ :lhs user-id-by-name)]
+ "filters" [["not-null" {} min-ref]]}))]
+ (testing "the ref isn't typed from the previous stage's same-named column, and nothing is raised"
+ (is (= min-ref (get-in (repair* q) ["stages" 1 "filters" 0 2]))))))
+
+(deftest ^:parallel join-alias-field-type-runs-before-cross-stage-inference-test
+ (testing "a stage carrying a join-alias ref still resolves as the next stage's prefix"
+ (let [out (repair* (query (orders-stage {"joins" [(join "First" [first-orders-stage])]
+ "aggregation" [["count" {}]]
+ "breakout" [(join-ref "First" "min")]})
+ (stage {"filters" [[">" {} ["field" {} "count"] 1]]})))]
+ (is (= "type/Date" (base-type (get-in out ["stages" 0 "breakout" 0]))))
+ (is (= "type/Integer" (base-type (get-in out ["stages" 1 "filters" 0 2])))))))
+
+(deftest join-alias-field-type-resolves-each-join-at-most-once-test
+ (let [resolutions (fn [join-stages q]
+ (let [calls (atom 0)
+ resolve (mt/original-fn #'repr.resolve/resolve-query)]
+ (mt/with-dynamic-fn-redefs [repr.resolve/resolve-query (fn [mp query store]
+ (when (= join-stages (get query "stages"))
+ (swap! calls inc))
+ (resolve mp query store))]
+ (repair* q))
+ @calls))]
+ (testing "a join named only by already-typed by-name refs is resolved once, to check them"
+ (is (= 1 (resolutions [first-orders-stage]
+ (query (orders-stage {"joins" [(-> (join "First" [first-orders-stage])
+ (assoc-in ["conditions" 0 3] (typed (join-ref "First" "USER_ID") "type/Integer")))]
+ "filters" [["not-null" {} (typed (join-ref "First" "min") "type/Date")]]}))))))
+ (testing "a grouped join named by both by-name and path refs is resolved once"
+ (is (= 1 (resolutions [first-orders-stage] first-order-query))))
+ (testing "a path ref into a plain table join doesn't resolve it"
+ (is (zero? (resolutions [(orders-stage {})]
+ (query (orders-stage {"joins" [(join "Plain" [(orders-stage {})])]
+ "filters" [["not-null" {} (join-ref "Plain" (conj orders "TOTAL"))]]}))))))))
+
+(deftest ^:parallel join-alias-field-type-idempotent-test
+ (let [once (repair* first-order-query)]
+ (is (= once (repair* once)))))
+
+(defn- first-orders-filtering [& refs]
+ (query (orders-stage {"joins" [(join "First" [first-orders-stage])]
+ "filters" (mapv #(vector "not-null" {} %) refs)})))
+
+(deftest ^:parallel join-alias-field-type-unknown-column-raises-test
+ (testing "a source column the grouped join doesn't return, referenced by name, raises"
+ (let [total-ref (join-ref "First" "TOTAL")
+ e (repair-error (first-orders-filtering total-ref))]
+ (is (=? {:agent-error? true
+ :error :unresolved-join-alias-field
+ :problems [{:stage 0 :join-alias "First" :clauses [total-ref] :columns ["TOTAL"] :available ["USER_ID" "min"]}]}
+ e))
+ (is (re-find #"join \"First\" doesn't return \"TOTAL\" \(available: USER_ID, min\)" (:message e)))))
+ (testing "every bad ref is reported in one error, across refs, joins, and stages"
+ (is (= [[0 "First" ["nope" "ORDERS.TOTAL"]] [0 "Second" ["nada"]] [1 "First" ["zilch"]]]
+ (join-problems
+ (query (orders-stage {"joins" [(join "First" [first-orders-stage]) (join "Second" [first-orders-stage])]
+ "filters" [["not-null" {} (join-ref "First" "nope")]
+ ["not-null" {} (join-ref "First" (conj orders "TOTAL"))]
+ ["not-null" {} (join-ref "Second" "nada")]]})
+ (stage {"joins" [(join "First" [first-orders-stage] :lhs user-id-by-name)]
+ "filters" [["not-null" {} (join-ref "First" "zilch")]]}))))))
+ (testing "a bad ref repeated in several clauses is listed once"
+ (is (= [[0 "First" ["nope"]]]
+ (join-problems (first-orders-filtering (join-ref "First" "nope") (join-ref "First" "nope"))))))
+ (testing "a by-name ref the LLM typed itself is checked too"
+ (is (= [[0 "First" ["nope"]]]
+ (join-problems (first-orders-filtering (typed (join-ref "First" "nope") "type/Text"))))))
+ (testing "a by-name ref the LLM typed itself keeps its type when the join returns the column"
+ (is (= "type/Text"
+ (base-type (get-in (repair* (first-orders-filtering (typed (join-ref "First" "min") "type/Text")))
+ ["stages" 0 "filters" 0 2]))))))
+
+(defn- filtering-through [alias stages column]
+ (query (orders-stage {"joins" [(join alias stages)]
+ "filters" [["not-null" {} (join-ref alias (conj orders column))]]})))
+
+(deftest ^:parallel join-alias-path-ref-must-be-returned-by-the-join-test
+ (testing "a path ref to a column the grouped join drops raises"
+ (is (= [[0 "First" ["ORDERS.TOTAL"]]] (join-problems (filtering-through "First" [first-orders-stage] "TOTAL")))))
+ (testing "a path ref to the grouped join's breakout column is accepted"
+ (is (nil? (repair-error (filtering-through "First" [first-orders-stage] "USER_ID")))))
+ (testing "a join narrowed with `fields:` is checked"
+ (is (= [[0 "Narrow" ["ORDERS.TOTAL"]]]
+ (join-problems (filtering-through "Narrow" [(orders-stage {"fields" [(orders-col "USER_ID")]})] "TOTAL")))))
+ (testing "a two-stage join is checked"
+ (is (= [[0 "Two" ["ORDERS.TOTAL"]]]
+ (join-problems (filtering-through "Two" [(orders-stage {}) (stage {"fields" [user-id-by-name]})] "TOTAL")))))
+ (testing "through a native card, whose columns carry no field ids, a path ref matches by name"
+ (let [native [(stage {"source-card" native-orders-card-eid})]]
+ (is (nil? (repair-error (filtering-through "Native" native "CREATED_AT"))))
+ (is (= [[0 "Native" ["ORDERS.TOTAL"]]] (join-problems (filtering-through "Native" native "TOTAL"))))))
+ (testing "a path ref doesn't match a returned column of another table by name, and is reported with its table"
+ (let [e (repair-error (query (orders-stage {"joins" [(join "Narrow" [(orders-stage {"fields" [(orders-col "ID") (orders-col "USER_ID")]})])]
+ "filters" [["not-null" {} (join-ref "Narrow" ["Sample" "PUBLIC" "PEOPLE" "ID"])]]})))]
+ (is (=? {:error :unresolved-join-alias-field :problems [{:columns ["PEOPLE.ID"] :available ["ID" "USER_ID"]}]} e))
+ (is (re-find #"join \"Narrow\" doesn't return \"PEOPLE.ID\" \(available: ID, USER_ID\)" (:message e)))))
+ (testing "a numeric field id target is reported by its table and field names"
+ (binding [serdes.resolve/*numeric-ids-allowed?* true]
+ (is (= [[0 "First" ["ORDERS.TOTAL"]]] (join-problems (first-orders-filtering (join-ref "First" 101))))))))
+
+(deftest ^:parallel join-alias-path-ref-with-source-field-is-skipped-test
+ (testing "a path ref with source-field (an implicit hop from the joined table) isn't checked"
+ (is (nil? (repair-error (first-orders-filtering
+ (assoc-in (join-ref "First" (conj orders "TOTAL")) [1 "source-field"] (conj orders "USER_ID"))))))))
+
+(deftest ^:parallel join-alias-path-ref-unresolvable-field-is-skipped-test
+ (testing "a path to no real field is left for the resolver to report"
+ (is (nil? (repair-error (filtering-through "First" [first-orders-stage] "NOPE")))))
+ (testing "a numeric id of no real field is left for the resolver to report"
+ (binding [serdes.resolve/*numeric-ids-allowed?* true]
+ (is (nil? (repair-error (first-orders-filtering (join-ref "First" 999))))))))
diff --git a/test/metabase/metabot/tools/construct_representations_test.clj b/test/metabase/metabot/tools/construct_representations_test.clj
index 1beb6ea0ed6..c32c8fe5468 100644
--- a/test/metabase/metabot/tools/construct_representations_test.clj
+++ b/test/metabase/metabot/tools/construct_representations_test.clj
@@ -8,8 +8,9 @@
unknown name, ambiguous name, missing name, mismatched DB component in source-table)."
(:require
[clojure.string :as str]
- [clojure.test :refer [deftest is testing]]
+ [clojure.test :refer [are deftest is testing]]
[clojure.walk :as walk]
+ [malli.core :as mc]
[metabase.agent-lib.representations.repair :as repr.repair]
[metabase.api.common :as api]
[metabase.lib-be.core :as lib-be]
@@ -28,7 +29,8 @@
[metabase.models.serialization.resolve :as serdes.resolve]
[metabase.models.serialization.resolve.mp :as resolve.mp]
[metabase.test :as mt]
- [metabase.util.json :as json]))
+ [metabase.util.json :as json]
+ [metabase.util.malli.registry :as mr]))
(set! *warn-on-reflection* true)
@@ -633,7 +635,7 @@
(is (some? e))
(is (true? (:agent-error? (ex-data e))))
(is (= :query-not-runnable (:error (ex-data e))))
- (is (re-find #"`offset`" (ex-message e)))
+ (is (re-find #"`offset` cannot be custom columns" (ex-message e)))
(is (re-find #"non-aggregation expression" (ex-message e)))))))))
(deftest editor-gate-offset-in-filter-surfaces-error-end-to-end-test
@@ -751,7 +753,8 @@
;; exact shape that resolves structurally yet makes Lib.canRun false.
bad (assoc-in good [:stages 0 :breakout 0] [:field {} "PRODUCT_ID"])]
(is (nil? (#'construct/query-not-runnable-explanation good)))
- (is (some? (#'construct/query-not-runnable-explanation bad))))))))
+ (is (str/includes? (#'construct/query-not-runnable-explanation bad)
+ "[:stages 0 :breakout 0 1 :base-type]: a field reference by name is missing `base-type`")))))))
;;; ============================================================
;;; Step-9 contract: expressions (custom columns)
@@ -2047,3 +2050,85 @@
(is (true? (:agent-error? d)))
(is (= :temporal-unit-on-non-temporal-column (:error d)))
(is (str/includes? (ex-message e) (str "is a " type-name " column")))))))))))
+
+;;; ============================================================
+;;; BOT-2222: refs to a grouped join's columns
+;;; ============================================================
+
+(defn- smallest-order-query
+ "Compares each order's TOTAL with `target` through `ref-alias` (default `First`, a self-join
+ returning each product's smallest TOTAL as `min`)."
+ [target & {:keys [ref-alias] :or {ref-alias "First"}}]
+ (let [orders-col (fn [column] ["field" {} ["Sample" "PUBLIC" "ORDERS" column]])]
+ {"lib/type" "mbql/query"
+ "database" "Sample"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "joins" [{"alias" "First"
+ "strategy" "left-join"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "aggregation" [["min" {} (orders-col "TOTAL")]]
+ "breakout" [(orders-col "PRODUCT_ID")]}]
+ "conditions" [["=" {}
+ (orders-col "PRODUCT_ID")
+ ["field" {"join-alias" "First"} ["Sample" "PUBLIC" "ORDERS" "PRODUCT_ID"]]]]}]
+ "expressions" {"Smallest?" ["=" {} (orders-col "TOTAL") ["field" {"join-alias" ref-alias} target]]}}]}))
+
+(deftest grouped-join-aggregation-by-name-test
+ (with-mp-and-stubs!
+ (fn []
+ (testing "a ref to the grouped join's aggregation by name builds a query with the ref typed"
+ (let [result (construct/execute-representations-query (query-data (smallest-order-query "min")))]
+ (is (=? [:field {:join-alias "First" :base-type :type/Float} "min"]
+ (get-in result [:structured-output :query :stages 0 :expressions 0 3])))))
+ (testing "an unknown name is a retryable agent error"
+ (let [e (editor-rejection (smallest-order-query "nope"))]
+ (is (=? {:agent-error? true :status-code 400} (ex-data e)))
+ (is (str/includes? (ex-message e) "join \"First\" doesn't return \"nope\"")))))))
+
+(deftest ref-through-unknown-join-alias-explained-test
+ (testing "a by-name ref through an alias no join has is explained as an unresolved reference"
+ (with-mp-and-stubs!
+ (fn []
+ (let [e (editor-rejection (smallest-order-query "TOTAL" :ref-alias "Nope"))]
+ (is (=? {:agent-error? true :error :query-not-runnable :status-code 400} (ex-data e)))
+ (is (str/includes? (ex-message e) "could not be resolved")))))))
+
+(deftest path-ref-to-dropped-join-column-rejected-before-sql-test
+ (testing "a path ref to a column the grouped join drops fails in repair, not in the database"
+ (with-mp-and-stubs!
+ (fn []
+ (is (= :unresolved-join-alias-field
+ (:error (ex-data (editor-rejection (smallest-order-query ["Sample" "PUBLIC" "ORDERS" "ID"]))))))))))
+
+(deftest ^:parallel not-runnable-problem-test
+ (let [missing (fn [k] {:type :malli.core/missing-key :in [:stages 0 :breakout 0 1 k]})
+ invalid (fn [schema value] {:schema (mc/schema schema) :value value})]
+ (are [error re] (re-find re (#'construct/not-runnable-problem error))
+ (missing :lib/uuid) #"could not be resolved"
+ (missing :base-type) #"missing `base-type`"
+ (missing :alias) #"^missing `alias`$"
+ (invalid [:fn {:error/message "non-aggregation expression"} any?] 1) #"cannot be custom columns")
+ (testing "an error with no known cause is left to Malli's own message"
+ (is (nil? (#'construct/not-runnable-problem (invalid :int "x")))))))
+
+(deftest query-not-runnable-explanation-test
+ (let [explain (fn [& errors]
+ (mt/with-dynamic-fn-redefs [mr/explain (constantly {:errors errors})]
+ (#'construct/query-not-runnable-explanation {})))
+ missing (fn [k] {:type :malli.core/missing-key :in [:stages 0 k]})
+ invalid (fn [k] {:schema (mc/schema :int) :value "x" :in [:stages 0 k]})
+ hint #"\. This usually means a field reference is missing its type"]
+ (testing "identical problems are listed once"
+ (is (= "[:stages 0 :alias]: missing `alias`" (explain (missing :alias) (missing :alias)))))
+ (testing "at most three problems are listed"
+ (is (= 3 (count (str/split (apply explain (map missing [:a :b :c :d])) #"; ")))))
+ (testing "problems with a known cause are listed before Malli's own messages"
+ (is (str/starts-with? (explain (invalid :a) (invalid :b) (invalid :c) (missing :alias))
+ "[:stages 0 :alias]: missing `alias`; [:stages 0 :a]: should be an integer")))
+ (testing "the usual causes are added only when no problem has a known cause"
+ (is (re-find hint (explain (invalid :a))))
+ (is (not (re-find hint (explain (invalid :a) (missing :alias))))))
+ (testing "an explanation with no errors falls back to a generic sentence and the usual causes"
+ (is (str/starts-with? (explain) "the query does not match the query builder's schema. This usually means")))))