Skip to content

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

Data Complexity Score rating bands (#74271)

Chris Truter1e76db8e8309
diff --git a/enterprise/backend/src/metabase_enterprise/data_complexity_score/api.clj b/enterprise/backend/src/metabase_enterprise/data_complexity_score/api.clj
index a891d1f2e2a..9a2dae244fb 100644
--- a/enterprise/backend/src/metabase_enterprise/data_complexity_score/api.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_complexity_score/api.clj
@@ -15,29 +15,37 @@
(set! *warn-on-reflection* true)
-(def ^:private SubScore
- "Either a computed sub-score (`:measurement` + `:score`) or an uncomputed one (`:error`)."
- [:or
- [:map {:closed true}
- [:measurement number?]
- [:score nat-int?]]
- [:map {:closed true}
- [:measurement nil?]
- [:score nil?]
- [:error string?]]])
+(def ^:private Rating
+ "A rating band label drawn from `complexity-bands`."
+ [:enum "low" "medium" "high"])
-(def ^:private Catalog
- "One catalog's total + per-component breakdown.
- `:total` is nil when any sub-score couldn't be computed — failures cascade through aggregates."
- [:map
- [:total [:maybe nat-int?]]
- [:components
- [:map
- [:entity_count SubScore]
- [:name_collisions SubScore]
- [:synonym_pairs SubScore]
- [:field_count SubScore]
- [:repeated_measures SubScore]]]])
+(def ^:private Failure
+ "Sub-score that couldn't be computed; carries only the failure message.
+ (Named `Failure` rather than `Error` to avoid shadowing `java.lang.Error`.)"
+ [:map {:closed true}
+ [:error string?]])
+
+(def ^:private Leaf
+ "Computed leaf sub-score with a raw `:measurement` and its weighted `:score`."
+ [:map {:closed true}
+ [:measurement number?]
+ [:score nat-int?]
+ [:rating [:maybe Rating]]
+ [:rating_label [:maybe string?]]])
+
+(def ^:private Grouping
+ "Internal node whose `:score` is the rolled-up sum of its `:components` children."
+ [:map {:closed true}
+ [:score [:maybe nat-int?]]
+ [:rating [:maybe Rating]]
+ [:rating_label [:maybe string?]]
+ [:components [:map-of :keyword [:ref ::node]]]])
+
+(def ^:private Node
+ "Recursive score node: a [[Failure]], a [[Leaf]], or a [[Grouping]] whose children are themselves Nodes."
+ [:schema
+ {:registry {::node [:or Failure Leaf Grouping]}}
+ [:ref ::node]])
(def ^:private EmbeddingModelMeta
"Identifies the embedding model backing the synonym calculations, so benchmark consumers can pin to it.
@@ -50,12 +58,13 @@
(def ^:private ComplexityScoresResponse
"Full response body for `GET /api/ee/data-complexity-score/complexity`."
[:map
- [:library Catalog]
- [:universe Catalog]
- [:metabot Catalog]
+ [:library Node]
+ [:universe Node]
+ [:metabot Node]
[:meta
[:map
[:formula_version pos-int?]
+ [:format_version pos-int?]
[:synonym_threshold number?]
[:calculated_at {:optional true} some?]
[:embedding_model {:optional true} EmbeddingModelMeta]]]])
@@ -87,7 +96,7 @@
:metabot-scope (metabot-scope/internal-metabot-scope)))
stored (data-complexity-score/record-score! fingerprint "appdb" result)]
(task.complexity-score/maybe-advance-last-fingerprint! fingerprint result)
- (m.util/deep-snake-keys (or stored result)))
+ (m.util/deep-snake-keys (complexity/decorate-with-ratings (or stored result))))
(finally
(.set api-scoring-running? false))))
@@ -103,6 +112,7 @@
(if force-recalculation?
(force-recalculate-score!)
(api/check-404 (some-> (data-complexity-score/latest-score (task.complexity-score/current-fingerprint))
+ complexity/decorate-with-ratings
m.util/deep-snake-keys)
(tru "Data Complexity Score has not been computed yet. Recompute it to create the first snapshot."))))
diff --git a/enterprise/backend/src/metabase_enterprise/data_complexity_score/complexity.clj b/enterprise/backend/src/metabase_enterprise/data_complexity_score/complexity.clj
index 72d4d9492df..3a570bde5d6 100644
--- a/enterprise/backend/src/metabase_enterprise/data_complexity_score/complexity.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_complexity_score/complexity.clj
@@ -17,11 +17,13 @@
(set! *warn-on-reflection* true)
(def formula-version
- "Bump when the scoring formula changes in a way that would break historical comparisons.
+ "Bump when the scoring formula changes in a way that would break historical score comparisons.
+ Weight changes, new/removed components, and rollup-affecting restructures count; pure-shape changes do not.
+ Tunables in the fingerprint (`embedding-model`, `synonym-threshold`, `text-variant`, etc) don't need a bump."
+ 1)
- Changes to `embedding-model`, `synonym-threshold`, `text-variant`, etc don't need a bump.
- These parameters are already captured in the fingerprint.
- Formula versioning is reserved for cases where the actual formulas or components change."
+(def format-version
+ "Bump when the response shape changes in a way that breaks consumer parsing, even when scores are equivalent."
1)
(def weights
@@ -34,15 +36,70 @@
:field 1
:repeated-measure 2})
-(def ^:private component->group
- "Thematic parent per sub-component — drives the `<group>.total` + `<group>.<component>` rollup in
- emitted keys so operators can tell `size` from `ambiguity` without SQL.
- Must cover every key produced by [[score-catalog]] or the missing ones emit as `nil.<component>`."
- {:entity-count :size
- :field-count :size
- :name-collisions :ambiguity
- :synonym-pairs :ambiguity
- :repeated-measures :ambiguity})
+(def complexity-bands
+ "Tree of rating bands mirroring [[score-catalog]]'s output.
+ Each node's `:bands` rates that node's `:score`; `:components` follows the same nesting as the scored catalog."
+ {:bands [{:rating "low" :label "Low complexity" :max 999}
+ {:rating "medium" :label "Medium complexity" :max 9999}
+ {:rating "high" :label "High complexity"}]})
+
+(def ^:private nil-rating {:rating nil :rating-label nil})
+
+(defn- ->band-lookup
+ "Bundle `bands` with a pre-built `:rating`→presentation `:lookup` for fast rating-by-score."
+ [bands]
+ {:bands bands
+ :lookup (u/for-map [{:keys [rating label]} bands]
+ [rating {:rating rating :rating-label label}])})
+
+(defn- compile-bands
+ "Replace each node's `:bands` in the bands tree with a precomputed `:band-lookup`."
+ [bands]
+ (cond-> {}
+ (:bands bands)
+ (assoc :band-lookup (->band-lookup (:bands bands)))
+
+ (:components bands)
+ (assoc :components (update-vals (:components bands) compile-bands))))
+
+(def ^:private compiled-bands
+ (compile-bands complexity-bands))
+
+(defn- rating-for-score
+ "Look up `score`'s rating in a preprocessed `band-lookup`, or `nil-rating` when nothing matches."
+ [{:keys [bands lookup]} score]
+ (or (when (some? score)
+ (some (fn [{:keys [rating max]}]
+ (when (or (nil? max) (<= score max))
+ (lookup rating)))
+ bands))
+ nil-rating))
+
+(defn- decorate-with-ratings*
+ "Walk a catalog `node` and the matching `bands` subtree in parallel, merging rating fields onto every node.
+ Each node is rated against its own `:band-lookup`, or `nil-rating` when absent.
+ Error leaves carry only `:error` and are left untouched. Children recurse along `:components`."
+ [bands node]
+ (if (:error node)
+ node
+ (let [decorated (merge node (rating-for-score (:band-lookup bands) (:score node)))]
+ (cond-> decorated
+ (:components node)
+ (update :components
+ (fn [components]
+ (reduce-kv (fn [m k child]
+ (assoc m k (decorate-with-ratings* (get-in bands [:components k])
+ child)))
+ {}
+ components)))))))
+
+;; TODO: also emit the rating onto Snowplow events so benchmark consumers can correlate the band
+;; against the raw score without re-applying the bands.
+(defn decorate-with-ratings
+ "Decorate each catalog with rating fields per `complexity-bands`."
+ [score]
+ (let [decorate (partial decorate-with-ratings* compiled-bands)]
+ (reduce #(u/update-if-exists %1 %2 decorate) score [:library :universe :metabot])))
(def synonym-similarity-threshold
"Cosine-similarity cutoff for flagging two names as synonyms.
@@ -296,10 +353,10 @@
:value-doesnt-matter))))
(defn- score-synonym-pairs
- "Compute the synonym sub-score for `entities` using `embedder`. On embedder failure, returns nil
- `:score`/`:measurement` plus an `:error` string so the failure cascades through aggregates
- instead of being mistaken for a real zero. A nil `embedder` produces an empty lookup and scores
- a real zero."
+ "Compute the synonym sub-score for `entities` using `embedder`.
+ On embedder failure returns an `{:error \"...\"}`-only leaf, so the failure cascades through aggregates
+ (their `:score` rolls up to nil) and consumers can branch on `:error` presence.
+ A nil `embedder` produces an empty lookup and scores a real zero."
[entities embedder]
(try
(let [name->vec (or (and embedder (embedder entities)) {})
@@ -317,7 +374,7 @@
err (if (str/blank? msg)
(or (some-> (class t) .getName) "synonym detection failed")
msg)]
- {:measurement nil :score nil :error err}))))
+ {:error err}))))
(defn- nil-safe-sum
"Sum `xs` (numbers and/or nils). Returns nil if any element is nil — used to cascade an
@@ -326,16 +383,33 @@
(when (every? some? xs)
(reduce + xs)))
+(defn- score-tree-leaves
+ "Pure: build the leaves-only tree of sub-score maps for one catalog.
+ Each leaf is a `{:measurement <num-or-nil> :score <num-or-nil> [:error <str>]}` map; the surrounding shape
+ defines the `:size`/`:ambiguity` grouping that [[score-catalog]] then rolls up."
+ [entities embedder]
+ {:size {:entity-count (score-entity-count entities)
+ :field-count (score-field-count entities)}
+ :ambiguity {:name-collisions (score-name-collisions entities)
+ :synonym-pairs (score-synonym-pairs entities embedder)
+ :repeated-measures (score-repeated-measures entities)}})
+
+(defn- rollup-node
+ "Recursively roll up a node's children into `{:score <sum> :components {...}}`.
+ Leaves — maps carrying `:score` (computed) or `:error` (uncomputed) — pass through unchanged.
+ `:score` cascades nil through aggregates so an uncomputed sub-score nils out everything it feeds."
+ [node]
+ (if (or (contains? node :score) (contains? node :error))
+ node
+ (let [components (update-vals node rollup-node)]
+ {:score (nil-safe-sum (map (comp :score val) components))
+ :components components})))
+
(defn score-catalog
- "Pure: compute the score breakdown for a catalog given its `entities` and an optional `embedder`."
+ "Pure: compute the score breakdown for a catalog given its `entities` and an optional `embedder`.
+ Returns `{:score <sum> :components {:size {...} :ambiguity {...}}}`; see [[score-tree-leaves]] for the leaf layout."
[entities embedder]
- (let [components {:entity-count (score-entity-count entities)
- :name-collisions (score-name-collisions entities)
- :synonym-pairs (score-synonym-pairs entities embedder)
- :field-count (score-field-count entities)
- :repeated-measures (score-repeated-measures entities)}]
- {:total (nil-safe-sum (map (comp :score val) components))
- :components components}))
+ (rollup-node (score-tree-leaves entities embedder)))
;;; ----------------------------------- public API ------------------------------------
@@ -381,6 +455,23 @@
[event score]
(cond-> event (some? score) (assoc :score score)))
+(defn- node->events
+ "Walk one catalog and emit a Snowplow event per node.
+ Computed leaves use a `<path>` key and carry `:measurement`; error leaves use the same `<path>` key with `:error`.
+ Internal nodes use a `<path>.total` key with the rolled-up `:score` (the root emits as `total`).
+ `:score` is omitted when nil; see [[with-score]]."
+ [base catalog path node]
+ (let [;; `:total` here is the Snowplow wire-format suffix for rollup nodes, not an in-memory field.
+ key (apply dotted-key (if (:components node) (conj path :total) path))
+ event (cond-> (-> base
+ (assoc :catalog catalog :key key)
+ (with-score (:score node)))
+ (:measurement node) (assoc :measurement (:measurement node))
+ (:error node) (assoc :error (truncate-error (:error node))))]
+ (cons event
+ (mapcat (fn [[k child]] (node->events base catalog (conj path k) child))
+ (:components node)))))
+
(defn- emit-snowplow!
"Submits Snowplow events for every score, every group aggregation, and the grand total.
Returns true when they are all successfully delivered.
@@ -390,27 +481,8 @@
:batch_id (str (random-uuid))
:formula_version (:formula-version meta)
:parameters (parameters-map meta)}
- events (for [[catalog result] [[:library library] [:universe universe] [:metabot metabot]]
- event (concat (for [[component sub] (:components result)]
- ;; leaf component
- (cond-> (-> base
- (assoc :catalog catalog
- :key (dotted-key (component->group component) component)
- :measurement (:measurement sub))
- (with-score (:score sub)))
- (:error sub) (assoc :error (truncate-error (:error sub)))))
- (for [[group entries] (group-by #(component->group (key %)) (:components result))]
- ;; group total
- (-> base
- (assoc :catalog catalog
- :key (dotted-key group :total))
- (with-score (nil-safe-sum (map (comp :score val) entries)))))
- ;; grand total
- [(-> base
- (assoc :catalog catalog
- :key (dotted-key :total))
- (with-score (:total result)))])]
- event)]
+ events (mapcat (fn [[catalog result]] (node->events base catalog [] result))
+ [[:library library] [:universe universe] [:metabot metabot]])]
;; No short-circuiting - even if they are failures, attempt the rest.
(reduce (fn [all-ok? event]
(and (analytics/track-event! :snowplow/data_complexity event) all-ok?))
@@ -440,6 +512,7 @@
universe-score
(score-catalog metabot-entities embedder))
:meta (cond-> {:formula-version formula-version
+ :format-version format-version
:synonym-threshold synonym-similarity-threshold
:weights weights}
embedding-model-meta (assoc :embedding-model embedding-model-meta)
@@ -462,10 +535,11 @@
Returns a map of the shape:
- {:library {:total n :components {...}}
- :universe {:total n :components {...}}
- :metabot {:total n :components {...}}
+ {:library {:score n :components {...}}
+ :universe {:score n :components {...}}
+ :metabot {:score n :components {...}}
:meta {:formula-version 1
+ :format-version 1
:synonym-threshold 0.80
:embedding-model {:provider ..., :model-name ..., :model-dimensions ...}
:text-variant :names-split}}
@@ -506,6 +580,7 @@
:universe universe-score
:metabot metabot-score
:meta (cond-> {:formula-version formula-version
+ :format-version format-version
:synonym-threshold synonym-similarity-threshold}
embedding-model-meta (assoc :embedding-model embedding-model-meta)
text-variant (assoc :text-variant text-variant))}
diff --git a/enterprise/backend/src/metabase_enterprise/data_complexity_score/task/complexity_score.clj b/enterprise/backend/src/metabase_enterprise/data_complexity_score/task/complexity_score.clj
index 6130af978bd..f52f76b5a3a 100644
--- a/enterprise/backend/src/metabase_enterprise/data_complexity_score/task/complexity_score.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_complexity_score/task/complexity_score.clj
@@ -23,19 +23,13 @@
(def ^:private trigger-key (triggers/key "metabase.task.data-complexity-score.trigger"))
(defn current-fingerprint
- "String capturing everything that changes the meaning of an emitted score.
-
- Mirrors the Snowplow `formula_version` + `parameters` fields. `weights` is included so re-tuning
- forces a re-score without a `formula-version` bump; only structural scoring-algorithm changes
- need that.
-
- The synonym-axis fragment comes from [[synonym-source/fingerprint-fragment]] so the fingerprint
- reacts to the source toggle and the configured model — and on the search-index path also picks
- up swaps in the active pgvector model so a re-index that swaps the model invalidates prior
- scores."
+ "String capturing everything that changes the meaning or shape of an emitted score.
+ Includes `formula-version`, `format-version`, `weights`, `synonym-threshold`, and the synonym-axis fragment
+ from [[synonym-source/fingerprint-fragment]] (source toggles, configured embedder, pgvector index swaps)."
[]
(pr-str (into (sorted-map)
(merge {:formula-version complexity/formula-version
+ :format-version complexity/format-version
:synonym-threshold complexity/synonym-similarity-threshold
:weights complexity/weights}
(synonym-source/fingerprint-fragment)))))
diff --git a/enterprise/backend/test/metabase_enterprise/data_complexity_score/api_test.clj b/enterprise/backend/test/metabase_enterprise/data_complexity_score/api_test.clj
index f6eadcf0357..fd7d2ad4337 100644
--- a/enterprise/backend/test/metabase_enterprise/data_complexity_score/api_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_complexity_score/api_test.clj
@@ -56,27 +56,41 @@
(mt/user-http-request :rasta :get 403 endpoint :force-recalculation true)))))
(def ^:private sample-score
- {:library {:total 18
- :components {:entity-count {:measurement 1.0 :score 10}
- :name-collisions {:measurement 0.0 :score 0}
- :synonym-pairs {:measurement 0.0 :score 0}
- :field-count {:measurement 8.0 :score 8}
- :repeated-measures {:measurement 0.0 :score 0}}}
- :universe {:total 54
- :components {:entity-count {:measurement 2.0 :score 20}
- :name-collisions {:measurement 0.0 :score 0}
- :synonym-pairs {:measurement 0.0 :score 0}
- :field-count {:measurement 24.0 :score 24}
- :repeated-measures {:measurement 5.0 :score 10}}}
- :metabot {:total 30
- :components {:entity-count {:measurement 1.0 :score 10}
- :name-collisions {:measurement 0.0 :score 0}
- :synonym-pairs {:measurement 0.0 :score 0}
- :field-count {:measurement 20.0 :score 20}
- :repeated-measures {:measurement 0.0 :score 0}}}
- :meta {:formula-version 3
+ "Raw shape — what `complexity-scores` returns and what persistence stores.
+ The API decorates this with rating fields on the way out."
+ {:library {:score 18
+ :components {:size {:score 18
+ :components {:entity-count {:measurement 1.0 :score 10}
+ :field-count {:measurement 8.0 :score 8}}}
+ :ambiguity {:score 0
+ :components {:name-collisions {:measurement 0.0 :score 0}
+ :synonym-pairs {:measurement 0.0 :score 0}
+ :repeated-measures {:measurement 0.0 :score 0}}}}}
+ :universe {:score 54
+ :components {:size {:score 44
+ :components {:entity-count {:measurement 2.0 :score 20}
+ :field-count {:measurement 24.0 :score 24}}}
+ :ambiguity {:score 10
+ :components {:name-collisions {:measurement 0.0 :score 0}
+ :synonym-pairs {:measurement 0.0 :score 0}
+ :repeated-measures {:measurement 5.0 :score 10}}}}}
+ :metabot {:score 30
+ :components {:size {:score 30
+ :components {:entity-count {:measurement 1.0 :score 10}
+ :field-count {:measurement 20.0 :score 20}}}
+ :ambiguity {:score 0
+ :components {:name-collisions {:measurement 0.0 :score 0}
+ :synonym-pairs {:measurement 0.0 :score 0}
+ :repeated-measures {:measurement 0.0 :score 0}}}}}
+ :meta {:formula-version 3
+ :format-version 1
:synonym-threshold 0.9}})
+(defn- expected-response
+ "Apply the same decoration + snake-casing the API does, to compare against an `mt/user-http-request` body."
+ [score]
+ (m.util/deep-snake-keys (complexity/decorate-with-ratings score)))
+
(def ^:private sample-calculated-at "2026-04-23T12:00:00Z")
(defn- with-sample-calculated-at
@@ -94,12 +108,15 @@
(let [resp (mt/user-http-request :crowberto :get 200 endpoint)]
(is (= "api-test-fp" @captured-fingerprint)
"API passes the cron fingerprint through; source=\"appdb\" defaulting is covered by latest-score-filters-by-source-test")
- (is (= (m.util/deep-snake-keys (with-sample-calculated-at sample-score)) resp))
+ (is (= (expected-response (with-sample-calculated-at sample-score)) resp))
(is (contains? (:meta resp) :formula_version))
(is (= sample-calculated-at (get-in resp [:meta :calculated_at])))
(is (not (contains? (:meta resp) :formula-version)))
- (is (contains? (get-in resp [:library :components]) :entity_count))
- (is (not (contains? (get-in resp [:library :components]) :entity-count))))))))
+ (is (contains? (get-in resp [:library :components]) :size)
+ "groups appear at the catalog level")
+ (is (contains? (get-in resp [:library :components :size :components]) :entity_count)
+ "leaf sub-scores live one level down and are snake-cased")
+ (is (not (contains? (get-in resp [:library :components :size :components]) :entity-count))))))))
(deftest complexity-endpoint-404s-when-no-score-has-been-persisted-yet-test
(testing "the endpoint 404s until the background scorer has produced its first snapshot"
@@ -116,7 +133,7 @@
data-complexity-score/record-score! (fn [fingerprint source stored-score]
(reset! persisted? [fingerprint source stored-score])
(with-sample-calculated-at stored-score))]
- (is (= (m.util/deep-snake-keys (with-sample-calculated-at sample-score))
+ (is (= (expected-response (with-sample-calculated-at sample-score))
(mt/user-http-request :crowberto :get 200 endpoint :force-recalculation true)))
(is (= ["api-test-fp" "appdb" sample-score] @persisted?)
"API recompute path must stamp source=\"appdb\"")))))
@@ -156,7 +173,7 @@
task.complexity-score/current-fingerprint (constantly "api-test-fp")
complexity/complexity-scores (fn [& _] sample-score)
data-complexity-score/record-score! (fn [& _] nil)]
- (is (= (m.util/deep-snake-keys sample-score)
+ (is (= (expected-response sample-score)
(mt/user-http-request :crowberto :get 200 endpoint :force-recalculation true)))))))
(deftest ^:sequential complexity-endpoint-force-recalculation-superuser-gets-consistent-totals-test
@@ -169,8 +186,16 @@
(constantly {:embedder random-synonym-embedder})]
(with-redefs [data-complexity-score/record-score! (fn [& _] nil)]
(let [resp (mt/user-http-request :crowberto :get 200 endpoint :force-recalculation true)
- measurement (fn [cat k] (get-in resp [cat :components k :measurement]))
- component-score (fn [cat k] (get-in resp [cat :components k :score]))
+ leaf-path {:entity_count [:size :entity_count]
+ :field_count [:size :field_count]
+ :name_collisions [:ambiguity :name_collisions]
+ :synonym_pairs [:ambiguity :synonym_pairs]
+ :repeated_measures [:ambiguity :repeated_measures]}
+ leaf-field (fn [cat k field]
+ (let [[group leaf] (leaf-path k)]
+ (get-in resp [cat :components group :components leaf field])))
+ measurement (fn [cat k] (leaf-field cat k :measurement))
+ component-score (fn [cat k] (leaf-field cat k :score))
;; NOTE: `:synonym_pairs` is intentionally included here even though it's *theoretically*
;; non-monotonic — `score-synonym-pairs` dedupes by normalized name and keeps whichever
;; embedding the provider returns for that name, so adding universe-only entities that
@@ -181,13 +206,15 @@
;; invariant holds, and asserting it keeps us honest about regressions in the common
;; case. If the edge case ever actually trips this, *that* is the surprising thing we
;; want to see and we'll deal with it then.
- component-keys [:entity_count :name_collisions :synonym_pairs
- :field_count :repeated_measures]]
- (testing ":total equals the sum of its component :score values"
+ component-keys (keys leaf-path)]
+ (testing ":score at every node equals the sum of its children's :score values"
(doseq [catalog [:library :universe :metabot]
- :let [{:keys [total components]} (get resp catalog)]]
- (is (= total (reduce + (map :score (vals components))))
- (format "%s :total should equal sum of component :score values" catalog))))
+ :let [{catalog-score :score :keys [components]} (get resp catalog)]]
+ (is (= catalog-score (reduce + (map :score (vals components))))
+ (format "%s :score should equal sum of group :score values" catalog))
+ (doseq [[group {grp-score :score grp-components :components}] components]
+ (is (= grp-score (reduce + (map :score (vals grp-components))))
+ (format "%s.%s :score should equal sum of leaf :score values" catalog group)))))
(testing "universe is a superset of library: every measurement and score >= library's"
(doseq [k component-keys
getter [measurement component-score]
@@ -228,8 +255,8 @@
{:use_verified_content true :collection_id nil}
(with-redefs [data-complexity-score/record-score! (fn [& _] nil)]
(let [resp (mt/user-http-request :crowberto :get 200 endpoint :force-recalculation true)]
- (is (< (get-in resp [:metabot :components :entity_count :measurement])
- (get-in resp [:universe :components :entity_count :measurement]))
+ (is (< (get-in resp [:metabot :components :size :components :entity_count :measurement])
+ (get-in resp [:universe :components :size :components :entity_count :measurement]))
":metabot entity-count must be strictly < :universe when verified-only filters out the injected Card"))))))))
(deftest ^:sequential complexity-endpoint-force-recalculation-metabot-collection-scope-test
@@ -275,8 +302,8 @@
:collection_id cid}
(with-redefs [data-complexity-score/record-score! (fn [& _] nil)]
(let [resp (mt/user-http-request :crowberto :get 200 endpoint :force-recalculation true)]
- {:metabot (get-in resp [:metabot :components :entity_count :measurement])
- :universe (get-in resp [:universe :components :entity_count :measurement])}))))
+ {:metabot (get-in resp [:metabot :components :size :components :entity_count :measurement])
+ :universe (get-in resp [:universe :components :size :components :entity_count :measurement])}))))
empty-counts (counts-with-scope empty-id)
parent-counts (counts-with-scope parent-id)
sibling-counts (counts-with-scope sibling-id)
@@ -305,15 +332,18 @@
":universe must be unscoped regardless of Metabot.collection_id")))))))
(def ^:private empty-catalog
- {:total 0 :components {:entity-count {:measurement 0.0 :score 0}
- :name-collisions {:measurement 0.0 :score 0}
- :synonym-pairs {:measurement 0.0 :score 0}
- :field-count {:measurement 0.0 :score 0}
- :repeated-measures {:measurement 0.0 :score 0}}})
+ {:score 0
+ :components {:size {:score 0
+ :components {:entity-count {:measurement 0.0 :score 0}
+ :field-count {:measurement 0.0 :score 0}}}
+ :ambiguity {:score 0
+ :components {:name-collisions {:measurement 0.0 :score 0}
+ :synonym-pairs {:measurement 0.0 :score 0}
+ :repeated-measures {:measurement 0.0 :score 0}}}}})
(def ^:private stub-scores
{:library empty-catalog :universe empty-catalog :metabot empty-catalog
- :meta {:formula-version 1 :synonym-threshold 0.0}})
+ :meta {:formula-version 1 :format-version 1 :synonym-threshold 0.0}})
(deftest ^:sequential complexity-endpoint-force-recalculation-allows-active-scheduled-claim-test
(testing "manual API recalculation does not share the cron/boot scoring claim"
@@ -329,7 +359,7 @@
(fn [& _]
(reset! scoring-ran? true)
stub-scores)]
- (is (= (m.util/deep-snake-keys stub-scores)
+ (is (= (expected-response stub-scores)
(mt/user-http-request :crowberto :get 200 endpoint :force-recalculation true)))
(is (true? @scoring-ran?)
"force recalculation should compute independently of scheduled claims")
diff --git a/enterprise/backend/test/metabase_enterprise/data_complexity_score/cli_test.clj b/enterprise/backend/test/metabase_enterprise/data_complexity_score/cli_test.clj
index a99e45a40f1..c1c45be903e 100644
--- a/enterprise/backend/test/metabase_enterprise/data_complexity_score/cli_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_complexity_score/cli_test.clj
@@ -44,23 +44,36 @@
;; events (extra universe repeat).
(let [result (#'cli/run-cli {:representation-dir representation-fixture-dir})]
(testing "library score matches the hand-derived total"
- (is (= {:total 215
- :components {:entity-count {:measurement 6.0 :score 60}
- :name-collisions {:measurement 1.0 :score 100}
- :synonym-pairs {:measurement 1.0 :score 50}
- :field-count {:measurement 3.0 :score 3}
- :repeated-measures {:measurement 1.0 :score 2}}}
+ ;; size = 60 (entity) + 3 (field) = 63
+ ;; amb = 100 (collisions) + 50 (synonyms) + 2 (repeated-measures) = 152
+ ;; total = 215
+ (is (= {:score 215
+ :components {:size {:score 63
+ :components {:entity-count {:measurement 6.0 :score 60}
+ :field-count {:measurement 3.0 :score 3}}}
+ :ambiguity {:score 152
+ :components {:name-collisions {:measurement 1.0 :score 100}
+ :synonym-pairs {:measurement 1.0 :score 50}
+ :repeated-measures {:measurement 1.0 :score 2}}}}}
(:library result))))
(testing "universe score matches the hand-derived total"
- (is (= {:total 409
- :components {:entity-count {:measurement 10.0 :score 100}
- :name-collisions {:measurement 2.0 :score 200}
- :synonym-pairs {:measurement 2.0 :score 100}
- :field-count {:measurement 5.0 :score 5}
- :repeated-measures {:measurement 2.0 :score 4}}}
+ ;; size = 100 (entity) + 5 (field) = 105
+ ;; amb = 200 (collisions) + 100 (synonyms) + 4 (repeated-measures) = 304
+ ;; total = 409
+ (is (= {:score 409
+ :components {:size {:score 105
+ :components {:entity-count {:measurement 10.0 :score 100}
+ :field-count {:measurement 5.0 :score 5}}}
+ :ambiguity {:score 304
+ :components {:name-collisions {:measurement 2.0 :score 200}
+ :synonym-pairs {:measurement 2.0 :score 100}
+ :repeated-measures {:measurement 2.0 :score 4}}}}}
(:universe result))))
- (testing "meta has formula-version + threshold + weights but no :embedding-model (offline mode)"
+ (testing "meta has formula-version + format-version + threshold + weights but no :embedding-model (offline mode)"
+ ;; Literal 1/1 here is intentional — flags accidental version bumps that would invalidate the
+ ;; emitted fingerprint without an explicit code-change reviewer call.
(is (= {:formula-version 1
+ :format-version 1
:synonym-threshold 0.8
:weights complexity/weights
:metabot-source :universe-fallback}
@@ -97,13 +110,13 @@
(let [result (#'cli/run-cli {:representation-dir representation-fixture-dir})]
(testing "without --output, stdout gets single-line JSON"
(let [stdout (with-out-str (#'cli/write-result! result nil))]
- (is (= 215 (-> stdout (json/decode true) :library :total)))
+ (is (= 215 (-> stdout (json/decode true) :library :score)))
(is (not (re-find #"\n.+" stdout)) "stdout JSON should be single-line")))
(testing "with --output, the file gets pretty JSON and stdout stays silent"
(let [tmp (doto (java.io.File/createTempFile "complexity-cli-output-" ".json") .deleteOnExit)
stdout (with-out-str (#'cli/write-result! result (.getAbsolutePath tmp)))]
(is (= "" stdout))
- (is (= 215 (-> (slurp tmp) (json/decode true) :library :total)))))))
+ (is (= 215 (-> (slurp tmp) (json/decode true) :library :score)))))))
;;; ------------------------------------- pure embedder/scoring tests -------------------------------------
@@ -134,7 +147,7 @@
[]
(embedders/file-embedder embeddings)
{})
- [:library :components :synonym-pairs :measurement]))]
+ [:library :components :ambiguity :components :synonym-pairs :measurement]))]
(testing "cosine ≈ 0.50 — above the old 0.30 cutoff, below 0.80: NOT a synonym"
(is (= 0.0 (score-pairs {"alpha" [1.0 0.0]
"beta" [0.5 0.866]}))))
diff --git a/enterprise/backend/test/metabase_enterprise/data_complexity_score/complexity_test.clj b/enterprise/backend/test/metabase_enterprise/data_complexity_score/complexity_test.clj
index 626fd5e024b..6b8deed3e43 100644
--- a/enterprise/backend/test/metabase_enterprise/data_complexity_score/complexity_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_complexity_score/complexity_test.clj
@@ -50,56 +50,150 @@
(mapv #(when-let [v (get name->vec-literal %)] (float-array v)) names))))
(deftest ^:parallel score-catalog-pure-test
- (testing "empty catalog scores zero"
- (is (=? {:total 0
- :components {:entity-count {:measurement 0.0 :score 0}
- :name-collisions {:measurement 0.0 :score 0}
- :synonym-pairs {:measurement 0.0 :score 0}
- :field-count {:measurement 0.0 :score 0}
- :repeated-measures {:measurement 0.0 :score 0}}}
+ (testing "empty catalog scores zero — every leaf reports the zero, group totals roll up zero"
+ (is (=? {:score 0
+ :components {:size {:score 0
+ :components {:entity-count {:measurement 0.0 :score 0}
+ :field-count {:measurement 0.0 :score 0}}}
+ :ambiguity {:score 0
+ :components {:name-collisions {:measurement 0.0 :score 0}
+ :synonym-pairs {:measurement 0.0 :score 0}
+ :repeated-measures {:measurement 0.0 :score 0}}}}}
(#'complexity/score-catalog [] nil))))
- (testing "entity count contributes +10 per entity"
+ (testing "entity count contributes +10 per entity (lives under :size)"
(let [es [(entity :name "orders")
(entity :name "customers")
(entity :name "products")]]
- (is (=? {:total 30
- :components {:entity-count {:measurement 3.0 :score 30}}}
+ (is (=? {:score 30
+ :components {:size {:score 30
+ :components {:entity-count {:measurement 3.0 :score 30}}}}}
(#'complexity/score-catalog es nil)))))
- (testing "name collisions stack linearly: 3 identical names = +200"
+ (testing "name collisions stack linearly: 3 identical names = +200 (lives under :ambiguity)"
(let [es [(entity :name "orders")
(entity :name "orders")
(entity :name "orders")]]
- (is (=? {:components {:entity-count {:measurement 3.0 :score 30}
- :name-collisions {:measurement 2.0 :score 200}}}
+ (is (=? {:components {:size {:components {:entity-count {:measurement 3.0 :score 30}}}
+ :ambiguity {:components {:name-collisions {:measurement 2.0 :score 200}}}}}
(#'complexity/score-catalog es nil)))))
(testing "collision detection is case-insensitive and trims whitespace"
(let [es [(entity :name "Orders")
(entity :name " orders ")
(entity :name "ORDERS")]]
- (is (=? {:components {:name-collisions {:measurement 2.0 :score 200}}}
+ (is (=? {:components {:ambiguity {:components {:name-collisions {:measurement 2.0 :score 200}}}}}
(#'complexity/score-catalog es nil)))))
- (testing "field count contributes +1 per field, summed across entities"
+ (testing "field count contributes +1 per field (lives under :size, summed across entities)"
(let [es [(entity :name "a" :field-count 10)
(entity :name "b" :field-count 25)]]
- (is (=? {:components {:field-count {:measurement 35.0 :score 35}}}
+ (is (=? {:components {:size {:components {:field-count {:measurement 35.0 :score 35}}}}}
(#'complexity/score-catalog es nil)))))
- (testing "repeated measures contribute +2 per repeat (measure name appearing on >1 entity)"
+ (testing "repeated measures contribute +2 per repeat (lives under :ambiguity)"
(let [es [(entity :name "invoices" :measure-names ["revenue" "discount"])
(entity :name "subscriptions" :measure-names ["revenue"])
(entity :name "products" :measure-names ["price"])]]
- (is (=? {:components {:repeated-measures {:measurement 1.0 :score 2}}}
+ (is (=? {:components {:ambiguity {:components {:repeated-measures {:measurement 1.0 :score 2}}}}}
(#'complexity/score-catalog es nil)))))
(testing "nil embedder disables synonym scoring"
(let [es [(entity :name "customers") (entity :name "clients")]]
- (is (=? {:components {:synonym-pairs {:measurement 0.0 :score 0}}}
+ (is (=? {:components {:ambiguity {:components {:synonym-pairs {:measurement 0.0 :score 0}}}}}
(#'complexity/score-catalog es nil))))))
+(deftest ^:parallel complexity-bands-well-formed-test
+ (testing "every band list in the bands tree: last entry is unbounded; earlier entries have strictly ascending :max"
+ (let [collect-bands (fn collect-bands [node]
+ (concat (when-let [bands (:bands node)] [bands])
+ (mapcat collect-bands (vals (:components node)))))]
+ (doseq [bands (collect-bands complexity/complexity-bands)
+ :let [bounded (butlast bands)
+ unbounded (last bands)]]
+ (testing (str "bands=" bands)
+ (is (every? :max bounded))
+ (is (not (contains? unbounded :max)))
+ (when (next bounded)
+ (is (apply < (map :max bounded)))))))))
+
+(deftest ^:parallel rating-for-score-boundaries-test
+ (let [root-lookup (:band-lookup @#'complexity/compiled-bands)
+ cases [[0 {:rating "low" :rating-label "Low complexity"}]
+ [999 {:rating "low" :rating-label "Low complexity"}]
+ [1000 {:rating "medium" :rating-label "Medium complexity"}]
+ [9999 {:rating "medium" :rating-label "Medium complexity"}]
+ [10000 {:rating "high" :rating-label "High complexity"}]
+ [1e9 {:rating "high" :rating-label "High complexity"}]
+ [nil {:rating nil :rating-label nil}]]]
+ (testing "root band-lookup is populated (per-group/per-leaf bands land here once configured)"
+ (is (some? root-lookup)))
+ (doseq [[score expected] cases]
+ (testing (str "root score=" score)
+ (is (= expected (@#'complexity/rating-for-score root-lookup score))))))
+ (testing "nil or empty band-lookup falls through to nil-rating"
+ (is (= {:rating nil :rating-label nil} (@#'complexity/rating-for-score nil 12345)))
+ (is (= {:rating nil :rating-label nil} (@#'complexity/rating-for-score {} 12345)))))
+
+(deftest ^:parallel decorate-with-ratings-test
+ (testing "every node (root catalog, group, leaf) gets rating keys; nodes without configured bands get nil ratings"
+ (is (=? {:library {:score 0
+ :rating "low"
+ :rating-label "Low complexity"
+ :components {:size {:score 0
+ :rating nil
+ :rating-label nil
+ :components {:entity-count {:measurement 0.0
+ :score 0
+ :rating nil
+ :rating-label nil}}}}}
+ :universe {:score 1500
+ :rating "medium"
+ :rating-label "Medium complexity"}
+ :metabot {:score nil
+ :rating nil
+ :rating-label nil}}
+ (complexity/decorate-with-ratings
+ {:library {:score 0
+ :components {:size {:score 0
+ :components {:entity-count {:measurement 0.0
+ :score 0}}}}}
+ :universe {:score 1500
+ :components {}}
+ :metabot {:score nil
+ :components {}}}))))
+ (testing "missing catalogs are left alone (no rating fields injected)"
+ (is (= {:meta {:formula-version 1}}
+ (complexity/decorate-with-ratings {:meta {:formula-version 1}})))))
+
+(deftest ^:parallel decorate-with-ratings*-component-bands-test
+ (testing "bands at any depth get applied; nodes without bands cascade nil-rating"
+ (let [bands (@#'complexity/compile-bands
+ {:bands [{:rating "small" :label "Small" :max 100}
+ {:rating "big" :label "Big"}]
+ :components {:size {:components {:entity-count
+ {:bands [{:rating "few" :label "Few" :max 5}
+ {:rating "many" :label "Many"}]}}}}})
+ catalog {:score 150
+ :components {:size {:score 58
+ :components {:entity-count {:measurement 8.0 :score 8}
+ :field-count {:measurement 50.0 :score 50}}}}}]
+ (is (=? {:score 150
+ :rating "big"
+ :rating-label "Big"
+ :components {:size {:score 58
+ :rating nil
+ :rating-label nil
+ :components {:entity-count {:measurement 8.0
+ :score 8
+ :rating "many"
+ :rating-label "Many"}
+ :field-count {:measurement 50.0
+ :score 50
+ :rating nil
+ :rating-label nil}}}}}
+ (@#'complexity/decorate-with-ratings* bands catalog))))))
+
(deftest ^:parallel score-from-entities-metabot-fallback-test
(testing "score-from-entities marks :metabot as a universe fallback when no metabot-entities are passed"
(let [library []
@@ -123,22 +217,22 @@
(let [es [(entity :name "customers") (entity :name "clients")]
embedder (mock-embedder {"customers" [1.0 0.0 0.0]
"clients" [0.9 0.1 0.0]})]
- (is (=? {:components {:synonym-pairs {:measurement 1.0 :score 50}}}
+ (is (=? {:components {:ambiguity {:components {:synonym-pairs {:measurement 1.0 :score 50}}}}}
(#'complexity/score-catalog es embedder)))))
(testing "orthogonal embeddings produce no synonym pairs"
(let [es [(entity :name "customers") (entity :name "widgets")]
embedder (mock-embedder {"customers" [1.0 0.0]
"widgets" [0.0 1.0]})]
- (is (=? {:components {:synonym-pairs {:measurement 0.0 :score 0}}}
+ (is (=? {:components {:ambiguity {:components {:synonym-pairs {:measurement 0.0 :score 0}}}}}
(#'complexity/score-catalog es embedder)))))
(testing "exact-name duplicates don't double-count as synonym pairs"
(let [es [(entity :name "orders") (entity :name "orders") (entity :name "tickets")]
embedder (mock-embedder {"orders" [1.0 0.0]
"tickets" [0.0 1.0]})]
- (is (=? {:components {:name-collisions {:measurement 1.0 :score 100}
- :synonym-pairs {:measurement 0.0 :score 0}}}
+ (is (=? {:components {:ambiguity {:components {:name-collisions {:measurement 1.0 :score 100}
+ :synonym-pairs {:measurement 0.0 :score 0}}}}}
(#'complexity/score-catalog es embedder)))))
(testing "entities without a vector from the embedder are simply skipped"
@@ -146,33 +240,38 @@
;; "ghost" is missing → not considered. The remaining two are synonyms.
embedder (mock-embedder {"customers" [1.0 0.0]
"clients" [0.99 0.01]})]
- (is (=? {:components {:synonym-pairs {:measurement 1.0 :score 50}}}
+ (is (=? {:components {:ambiguity {:components {:synonym-pairs {:measurement 1.0 :score 50}}}}}
(#'complexity/score-catalog es embedder)))))
(testing "embedder failure cascades nil through the catalog (no zero-fallback)"
(let [es [(entity :name "customers") (entity :name "clients")]
embedder (fn [_] (throw (ex-info "boom" {})))]
- (is (=? {:total nil
- :components {:synonym-pairs {:measurement nil :score nil :error "boom"}
- ;; Sibling sub-scores still compute their real values — only the rollup
- ;; cascades nil — so consumers can still see the unaffected dimensions.
- :entity-count {:measurement 2.0 :score 20}}}
- (#'complexity/score-catalog es embedder)))))
+ (is (= {:score nil
+ :components {:ambiguity {:score nil
+ :components {:name-collisions {:measurement 0.0 :score 0}
+ :synonym-pairs {:error "boom"}
+ :repeated-measures {:measurement 0.0 :score 0}}}
+ ;; Sibling sub-scores still compute their real values — only aggregates
+ ;; that include the failed leaf cascade nil, so consumers can still see
+ ;; the unaffected dimensions.
+ :size {:score 20
+ :components {:entity-count {:measurement 2.0 :score 20}
+ :field-count {:measurement 0.0 :score 0}}}}}
+ (#'complexity/score-catalog es embedder)))))
(testing "throwable with a nil/blank message still records :error as a nonblank string"
;; Regression: we must keep :error present so an embedder failure is distinguishable from a
;; genuine zero-synonym result. Fall back to the exception class name.
(let [es [(entity :name "customers") (entity :name "clients")]
- synonym-of #(get-in (#'complexity/score-catalog es %) [:components :synonym-pairs])]
+ synonym-of #(get-in (#'complexity/score-catalog es %)
+ [:components :ambiguity :components :synonym-pairs])]
(doseq [[label embedder expected] [["nil message" (fn [_] (throw (NullPointerException.)))
"java.lang.NullPointerException"]
["blank message" (fn [_] (throw (RuntimeException. " ")))
"java.lang.RuntimeException"]]]
(testing label
- (let [sub (synonym-of embedder)]
- (is (nil? (:score sub)))
- (is (= expected (:error sub))
- (format ":error must be a nonblank string when the throwable's message is %s" label))))))))
+ (is (= {:error expected} (synonym-of embedder))
+ (format ":error must be a nonblank string when the throwable's message is %s" label)))))))
(deftest ^:sequential complexity-scores-metabot-scope-opt-test
(testing ":verified-only? true flows the caller's metabot-scope through to enumerate-catalogs"
@@ -188,8 +287,8 @@
:metabot-scope {:verified-only? true :collection-id nil})]
(is (= {:verified-only? true :collection-id nil} @captured-scope)
"enumerate-catalogs was invoked with the caller's scope")
- (is (= 1.0 (get-in metabot [:components :entity-count :measurement])))
- (is (= 2.0 (get-in universe [:components :entity-count :measurement])))))))
+ (is (= 1.0 (get-in metabot [:components :size :components :entity-count :measurement])))
+ (is (= 2.0 (get-in universe [:components :size :components :entity-count :measurement])))))))
(testing ":collection-id alone also flows through to enumerate-catalogs (no verified flag required)"
(let [captured-scope (atom nil)]
(mt/with-dynamic-fn-redefs [complexity/enumerate-catalogs
@@ -202,7 +301,7 @@
:embedder nil
:metabot-scope {:verified-only? false :collection-id 42})]
(is (= {:verified-only? false :collection-id 42} @captured-scope))
- (is (= 1.0 (get-in metabot [:components :entity-count :measurement])))))))
+ (is (= 1.0 (get-in metabot [:components :size :components :entity-count :measurement])))))))
(testing "empty scope (or no :metabot-scope opt) still runs enumerate-catalogs with that scope so metabot's table-visibility filter still narrows the catalog"
;; Regression: we used to reuse the :universe score verbatim when scope was empty. That hid the
;; fact that Metabot's table visibility (`:visibility_type nil`, non-routed DB) already narrows
@@ -221,8 +320,8 @@
(is (= scope @captured-scope)
(format "enumerate-catalogs was invoked with the caller's (possibly empty) scope=%s"
(pr-str scope)))
- (is (= 1.0 (get-in metabot [:components :entity-count :measurement])))
- (is (= 2.0 (get-in universe [:components :entity-count :measurement])))))))))
+ (is (= 1.0 (get-in metabot [:components :size :components :entity-count :measurement])))
+ (is (= 2.0 (get-in universe [:components :size :components :entity-count :measurement])))))))))
(deftest ^:sequential metabot-catalog-excludes-hidden-tables-test
(testing ":metabot tables filter out hidden (`visibility_type` non-nil) and routed-DB tables so the
@@ -293,15 +392,17 @@
:model/Table _ {:db_id db-id :name "contributes_to_universe" :active true}]
(let [{:keys [library universe]} (complexity/complexity-scores :embedder nil)]
(testing "library is empty (no collection tree)"
- (is (= {:total 0
- :components {:entity-count {:measurement 0.0 :score 0}
- :name-collisions {:measurement 0.0 :score 0}
- :synonym-pairs {:measurement 0.0 :score 0}
- :field-count {:measurement 0.0 :score 0}
- :repeated-measures {:measurement 0.0 :score 0}}}
+ (is (= {:score 0
+ :components {:size {:score 0
+ :components {:entity-count {:measurement 0.0 :score 0}
+ :field-count {:measurement 0.0 :score 0}}}
+ :ambiguity {:score 0
+ :components {:name-collisions {:measurement 0.0 :score 0}
+ :synonym-pairs {:measurement 0.0 :score 0}
+ :repeated-measures {:measurement 0.0 :score 0}}}}}
library)))
(testing "universe still enumerates appdb content (our temp table + whatever else is there)"
- (is (pos? (:total universe)))))))))
+ (is (pos? (:score universe)))))))))
(deftest ^:sequential library-excludes-audit-content-test
(testing "published audit-db content in the Library tree is excluded so :library stays a subset of :universe"
@@ -335,7 +436,7 @@
:archived false :collection_id mets-id}]
(with-redefs [audit/audit-db-id audit-db]
(let [{:keys [library]} (complexity/complexity-scores :embedder nil)]
- (is (= 2.0 (get-in library [:components :entity-count :measurement]))
+ (is (= 2.0 (get-in library [:components :size :components :entity-count :measurement]))
"only the two non-audit entities count (audit table + audit metric card excluded)"))))))
;; We're only reading the method table via `methods`, not calling the impure `!` fn — safe in parallel.
@@ -369,8 +470,8 @@
(semantic.tu/with-test-db! {:mode :mock-indexed}
(reset! captured (complexity/complexity-scores
:embedder semantic-search/search-index-embedder)))))
- (is (=? {:universe {:components {:synonym-pairs {:measurement number?
- :score nat-int?}}}}
+ (is (=? {:universe {:components {:ambiguity {:components {:synonym-pairs {:measurement number?
+ :score nat-int?}}}}}}
@captured)
"embedder returned vectors from pgvector and the synonym axis produced a real measurement")))))
@@ -389,9 +490,7 @@
[{:id 1 :name "orders" :kind :table}]))))
(testing "score-synonym-pairs converts the propagated failure into :error on the sub-score"
(let [es [(entity :name "customers") (entity :name "clients")]]
- (is (=? {:components {:synonym-pairs {:measurement nil
- :score nil
- :error string?}}}
+ (is (=? {:components {:ambiguity {:components {:synonym-pairs {:error string?}}}}}
(#'complexity/score-catalog es semantic-search/search-index-embedder))))))))
(defn- stub-fetch-batch
@@ -661,28 +760,22 @@
(map :data)
(filter #(= "data_complexity_scoring" (get % "event")))))
-(def ^:private leaf-key->group
- "Mirrors `complexity/component->group` for test assertions. Kept in snake-case string form
- (matching how keys land in the Snowplow payload)."
- {"entity_count" "size"
- "field_count" "size"
- "name_collisions" "ambiguity"
- "synonym_pairs" "ambiguity"
- "repeated_measures" "ambiguity"})
-
(defn- snake [k] (-> k name (str/replace "-" "_")))
(defn- expected-keys-for-catalog
- "For a catalog result, return `#{[key score], ...}` matching what emit-snowplow! should emit:
- grand `total`, one `<group>.total` per group, and one `<group>.<leaf>` per sub-component."
- [{:keys [total components]}]
- (let [leaves (into {} (map (fn [[k sub]] [(snake k) (:score sub)]) components))
- group-total (reduce-kv (fn [acc leaf score]
- (update acc (leaf-key->group leaf) (fnil + 0) score))
- {} leaves)]
- (set (concat [["total" total]]
- (for [[g s] group-total] [(str g ".total") s])
- (for [[leaf s] leaves] [(str (leaf-key->group leaf) "." leaf) s])))))
+ "For a catalog result, return `#{[wire-key score], ...}` matching what emit-snowplow! should emit:
+ grand `total`, one `<group>.total` per group, and one `<group>.<leaf>` per sub-component (the
+ `total` suffix is a Snowplow wire-format convention — the in-memory node uses `:score`). Walks
+ the score tree directly, so any future restructuring (extra depth, renamed groups) is exercised
+ by the helper and the production walk together."
+ [{root-score :score :keys [components]}]
+ (set
+ (cons ["total" root-score]
+ (for [[group {group-score :score group-components :components}] components
+ event (cons [(str (snake group) ".total") group-score]
+ (for [[leaf {:keys [score]}] group-components]
+ [(str (snake group) "." (snake leaf)) score]))]
+ event))))
(deftest ^:sequential emit-snowplow-publishes-total-and-each-subscore-test
(testing "one event per (catalog × key) — grand total, group rollups, and leaves — with correct scores"
@@ -843,8 +936,12 @@
analytics/track-event! (fn [& _] (throw (RuntimeException. "snowplow down")))]
(mt/with-log-messages-for-level [messages [metabase-enterprise.data-complexity-score.complexity :warn]]
(let [result (complexity/complexity-scores :embedder nil)]
- (is (=? {:library {:total 10 :components {:entity-count {:measurement 1.0 :score 10}}}
- :universe {:total 10 :components {:entity-count {:measurement 1.0 :score 10}}}}
+ (is (=? {:library {:score 10
+ :components {:size {:score 10
+ :components {:entity-count {:measurement 1.0 :score 10}}}}}
+ :universe {:score 10
+ :components {:size {:score 10
+ :components {:entity-count {:measurement 1.0 :score 10}}}}}}
result))
(is (some #(re-find #"Failed to publish complexity score" (:message %))
(messages))
@@ -939,18 +1036,20 @@
{:keys [library universe]} (complexity/complexity-scores :embedder embedder)]
(testing "library reflects exactly what we put in the Library collection tree"
;; Library: 4 tables + 2 metric cards = 6 entities.
- ;; entity-count 6 × 10 = 60
- ;; name-collisions "revenue" (2 metric cards) = 1 pair × 100 = 100
- ;; synonym-pairs clients ↔ customers = 1 × 50 = 50
+ ;; entity-count 6 × 10 = 60 → :size = 63
;; field-count orders(2) + subscriptions(1) + others(0) = 3 × 1 = 3
+ ;; name-collisions "revenue" (2 metric cards) = 1 pair × 100 = 100 → :ambiguity = 152
+ ;; synonym-pairs clients ↔ customers = 1 × 50 = 50
;; repeated-measures "revenue" on orders + subscriptions = 1 × 2 = 2
- ;; total 60 + 100 + 50 + 3 + 2 = 215
- (is (= {:total 215
- :components {:entity-count {:measurement 6.0 :score 60}
- :name-collisions {:measurement 1.0 :score 100}
- :synonym-pairs {:measurement 1.0 :score 50}
- :field-count {:measurement 3.0 :score 3}
- :repeated-measures {:measurement 1.0 :score 2}}}
+ ;; total 63 + 152 = 215
+ (is (= {:score 215
+ :components {:size {:score 63
+ :components {:entity-count {:measurement 6.0 :score 60}
+ :field-count {:measurement 3.0 :score 3}}}
+ :ambiguity {:score 152
+ :components {:name-collisions {:measurement 1.0 :score 100}
+ :synonym-pairs {:measurement 1.0 :score 50}
+ :repeated-measures {:measurement 1.0 :score 2}}}}}
library)))
(testing "universe is a strict superset of library on every component: every measurement and score is higher"
;; Note: :synonym-pairs is monotonic on this fixture but not in general — score-synonym-pairs
@@ -958,22 +1057,27 @@
;; sharing a normalized name with a library entity could in theory flip which vector wins and
;; decrease the pair count/score. Our fixture doesn't hit that case; if this assertion ever
;; flakes, that's the reason.
- (doseq [component [:entity-count :name-collisions :synonym-pairs :field-count :repeated-measures]
- k [:measurement :score]
- :let [lib-v (get-in library [:components component k])
- uni-v (get-in universe [:components component k])]]
+ (doseq [[group component] [[:size :entity-count]
+ [:ambiguity :name-collisions]
+ [:ambiguity :synonym-pairs]
+ [:size :field-count]
+ [:ambiguity :repeated-measures]]
+ k [:measurement :score]
+ :let [path [:components group :components component k]
+ lib-v (get-in library path)
+ uni-v (get-in universe path)]]
(is (> uni-v lib-v)
(format "universe %s %s (%s) should be strictly > library %s %s (%s)"
component k uni-v component k lib-v))))
(testing "universe total is strictly higher than library total"
- (is (> (:total universe) (:total library))))))))
+ (is (> (:score universe) (:score library))))))))
(defn- stub-result
"Build a `complexity/complexity-scores` stand-in whose metadata records whether publishing worked."
[published?]
(with-meta
- {:library {:total 0 :components {}} :universe {:total 0 :components {}}
- :metabot {:total 0 :components {}} :meta {}}
+ {:library {:score 0 :components {}} :universe {:score 0 :components {}}
+ :metabot {:score 0 :components {}} :meta {}}
{:metabase-enterprise.data-complexity-score.complexity/snowplow-published? published?}))
(deftest ^:sequential latest-score-filters-by-fingerprint-test
diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexityCards.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexityCards.tsx
index 4f74161cddf..9306b608f9d 100644
--- a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexityCards.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexityCards.tsx
@@ -26,18 +26,34 @@ import type {
DataComplexityCatalog,
DataComplexityCatalogId,
DataComplexityComponentId,
+ DataComplexityGroup,
+ DataComplexityGroupId,
+ DataComplexitySubScore,
} from "../../types";
+// Each group only carries its own component IDs (size: entity_count/field_count;
+// ambiguity: name_collisions/synonym_pairs/repeated_measures). The data-driven
+// iteration over COMPONENT_GROUPS uses the wide union, so cast to a permissive
+// view for the lookup — missing keys yield undefined.
+function getSubScore(
+ group: DataComplexityGroup,
+ componentId: DataComplexityComponentId,
+): DataComplexitySubScore | undefined {
+ return (
+ group.components as Partial<
+ Record<DataComplexityComponentId, DataComplexitySubScore>
+ >
+ )[componentId];
+}
+
const CATALOG_IDS: DataComplexityCatalogId[] = [
"library",
"universe",
"metabot",
];
-type DataComplexityComponentGroupId = "size" | "ambiguity";
-
const COMPONENT_GROUPS: {
- groupId: DataComplexityComponentGroupId;
+ groupId: DataComplexityGroupId;
componentIds: DataComplexityComponentId[];
}[] = [
{
@@ -97,11 +113,11 @@ function DataComplexityCard({
<Icon name="chevronright" size={12} c="text-tertiary" />
</Flex>
<Text c="text-secondary">{subtitle}</Text>
- {match(catalog.total)
- .with(P.number, (total) => (
+ {match(catalog.score)
+ .with(P.number, (score) => (
<Stack align="center" gap="sm" my="sm">
<Text size="4rem" fw={700}>
- {formatNumber(total, { maximumFractionDigits: 0 })}
+ {formatNumber(score, { maximumFractionDigits: 0 })}
</Text>
<Text c="text-secondary">{t`Lower is better`}</Text>
</Stack>
@@ -134,7 +150,7 @@ function DataComplexityBreakdown({
}: {
catalog: DataComplexityCatalog;
}) {
- const hasError = catalog.total == null;
+ const hasError = catalog.score == null;
return (
<Stack gap="lg">
@@ -155,6 +171,7 @@ function DataComplexityBreakdown({
description: t`Signals that similar or repeated names could make answers harder to trust.`,
}))
.exhaustive();
+ const group = catalog.components[groupId];
return (
<Box key={groupId}>
@@ -164,13 +181,19 @@ function DataComplexityBreakdown({
</Text>
<Stack gap="sm" mt="md">
- {componentIds.map((componentId) => (
- <DataComplexityComponentItem
- key={componentId}
- componentId={componentId}
- catalog={catalog}
- />
- ))}
+ {componentIds.map((componentId) => {
+ const component = getSubScore(group, componentId);
+ if (!component) {
+ return null;
+ }
+ return (
+ <DataComplexityComponentItem
+ key={componentId}
+ componentId={componentId}
+ component={component}
+ />
+ );
+ })}
</Stack>
</Box>
);
@@ -181,13 +204,12 @@ function DataComplexityBreakdown({
function DataComplexityComponentItem({
componentId,
- catalog,
+ component,
}: {
componentId: DataComplexityComponentId;
- catalog: DataComplexityCatalog;
+ component: DataComplexitySubScore;
}) {
- const component = catalog.components[componentId];
- const measurement = component.measurement;
+ const measurement = "measurement" in component ? component.measurement : null;
const { title, description, count } = match(componentId)
.with("entity_count", () => ({
@@ -263,7 +285,7 @@ function DataComplexityComponentItem({
<Text size="sm" c="text-secondary">
{description}
</Text>
- {component.score === null && (
+ {"error" in component && (
<Text mt="sm" size="sm" c="error" role="alert">
{component.error}
</Text>
diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexityCards.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexityCards.unit.spec.tsx
index a2dd4ac5f74..f982f78cd77 100644
--- a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexityCards.unit.spec.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexityCards.unit.spec.tsx
@@ -28,37 +28,68 @@ const cleanForSnapshot = (element: Element) => {
const mockScores: DataComplexityScoresResponse = {
library: {
- total: 18,
+ score: 18,
components: {
- entity_count: { measurement: 1, score: 10 },
- name_collisions: { measurement: 0, score: 0 },
- synonym_pairs: { measurement: 0, score: 0 },
- field_count: { measurement: 8, score: 8 },
- repeated_measures: { measurement: 0, score: 0 },
+ size: {
+ score: 18,
+ components: {
+ entity_count: { measurement: 1, score: 10 },
+ field_count: { measurement: 8, score: 8 },
+ },
+ },
+ ambiguity: {
+ score: 0,
+ components: {
+ name_collisions: { measurement: 0, score: 0 },
+ synonym_pairs: { measurement: 0, score: 0 },
+ repeated_measures: { measurement: 0, score: 0 },
+ },
+ },
},
},
universe: {
- total: 54,
+ score: 54,
components: {
- entity_count: { measurement: 2, score: 20 },
- name_collisions: { measurement: 0, score: 0 },
- synonym_pairs: { measurement: 0, score: 0 },
- field_count: { measurement: 24, score: 24 },
- repeated_measures: { measurement: 5, score: 10 },
+ size: {
+ score: 44,
+ components: {
+ entity_count: { measurement: 2, score: 20 },
+ field_count: { measurement: 24, score: 24 },
+ },
+ },
+ ambiguity: {
+ score: 10,
+ components: {
+ name_collisions: { measurement: 0, score: 0 },
+ synonym_pairs: { measurement: 0, score: 0 },
+ repeated_measures: { measurement: 5, score: 10 },
+ },
+ },
},
},
metabot: {
- total: 30,
+ score: 30,
components: {
- entity_count: { measurement: 1, score: 10 },
- name_collisions: { measurement: 0, score: 0 },
- synonym_pairs: { measurement: 0, score: 0 },
- field_count: { measurement: 20, score: 20 },
- repeated_measures: { measurement: 0, score: 0 },
+ size: {
+ score: 30,
+ components: {
+ entity_count: { measurement: 1, score: 10 },
+ field_count: { measurement: 20, score: 20 },
+ },
+ },
+ ambiguity: {
+ score: 0,
+ components: {
+ name_collisions: { measurement: 0, score: 0 },
+ synonym_pairs: { measurement: 0, score: 0 },
+ repeated_measures: { measurement: 0, score: 0 },
+ },
+ },
},
},
meta: {
formula_version: 3,
+ format_version: 1,
synonym_threshold: 0.9,
},
};
@@ -66,13 +97,17 @@ const mockScores: DataComplexityScoresResponse = {
const mockScoresWithError: DataComplexityScoresResponse = {
...mockScores,
metabot: {
- total: null,
+ score: null,
components: {
...mockScores.metabot.components,
- synonym_pairs: {
- measurement: null,
+ ambiguity: {
score: null,
- error: "Embedding service timed out",
+ components: {
+ ...mockScores.metabot.components.ambiguity.components,
+ synonym_pairs: {
+ error: "Embedding service timed out",
+ },
+ },
},
},
},
diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexitySection.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexitySection.unit.spec.tsx
index 20858c1b809..5854bf2c7bf 100644
--- a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexitySection.unit.spec.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/components/ConversationStatsPage/DataComplexitySection.unit.spec.tsx
@@ -11,37 +11,68 @@ import { DataComplexitySection } from "./ConversationStatsPage";
const mockScores: DataComplexityScoresResponse = {
library: {
- total: 18,
+ score: 18,
components: {
- entity_count: { measurement: 1, score: 10 },
- name_collisions: { measurement: 0, score: 0 },
- synonym_pairs: { measurement: 0, score: 0 },
- field_count: { measurement: 8, score: 8 },
- repeated_measures: { measurement: 0, score: 0 },
+ size: {
+ score: 18,
+ components: {
+ entity_count: { measurement: 1, score: 10 },
+ field_count: { measurement: 8, score: 8 },
+ },
+ },
+ ambiguity: {
+ score: 0,
+ components: {
+ name_collisions: { measurement: 0, score: 0 },
+ synonym_pairs: { measurement: 0, score: 0 },
+ repeated_measures: { measurement: 0, score: 0 },
+ },
+ },
},
},
universe: {
- total: 54,
+ score: 54,
components: {
- entity_count: { measurement: 2, score: 20 },
- name_collisions: { measurement: 0, score: 0 },
- synonym_pairs: { measurement: 0, score: 0 },
- field_count: { measurement: 24, score: 24 },
- repeated_measures: { measurement: 5, score: 10 },
+ size: {
+ score: 44,
+ components: {
+ entity_count: { measurement: 2, score: 20 },
+ field_count: { measurement: 24, score: 24 },
+ },
+ },
+ ambiguity: {
+ score: 10,
+ components: {
+ name_collisions: { measurement: 0, score: 0 },
+ synonym_pairs: { measurement: 0, score: 0 },
+ repeated_measures: { measurement: 5, score: 10 },
+ },
+ },
},
},
metabot: {
- total: 30,
+ score: 30,
components: {
- entity_count: { measurement: 1, score: 10 },
- name_collisions: { measurement: 0, score: 0 },
- synonym_pairs: { measurement: 0, score: 0 },
- field_count: { measurement: 20, score: 20 },
- repeated_measures: { measurement: 0, score: 0 },
+ size: {
+ score: 30,
+ components: {
+ entity_count: { measurement: 1, score: 10 },
+ field_count: { measurement: 20, score: 20 },
+ },
+ },
+ ambiguity: {
+ score: 0,
+ components: {
+ name_collisions: { measurement: 0, score: 0 },
+ synonym_pairs: { measurement: 0, score: 0 },
+ repeated_measures: { measurement: 0, score: 0 },
+ },
+ },
},
},
meta: {
formula_version: 3,
+ format_version: 1,
synonym_threshold: 0.9,
},
};
diff --git a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/types.ts b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/types.ts
index 665d5110a23..2cddd19eac1 100644
--- a/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/types.ts
+++ b/enterprise/frontend/src/metabase-enterprise/audit_app/metabot-analytics/types.ts
@@ -100,34 +100,50 @@ export type ConversationDetail = {
};
export type DataComplexityCatalogId = "library" | "universe" | "metabot";
-export type DataComplexityComponentId =
- | "entity_count"
+export type DataComplexityGroupId = "size" | "ambiguity";
+
+export type DataComplexitySizeComponentId = "entity_count" | "field_count";
+export type DataComplexityAmbiguityComponentId =
| "name_collisions"
| "synonym_pairs"
- | "field_count"
| "repeated_measures";
+export type DataComplexityComponentId =
+ | DataComplexitySizeComponentId
+ | DataComplexityAmbiguityComponentId;
export type DataComplexitySubScore =
- | {
- measurement: null;
- score: null;
- error: string;
- }
- | {
- measurement: number;
- score: number;
- };
+ | { error: string }
+ | { measurement: number; score: number };
+
+export type DataComplexitySizeGroup = {
+ score: number | null;
+ components: Record<DataComplexitySizeComponentId, DataComplexitySubScore>;
+};
+
+export type DataComplexityAmbiguityGroup = {
+ score: number | null;
+ components: Record<
+ DataComplexityAmbiguityComponentId,
+ DataComplexitySubScore
+ >;
+};
+
+export type DataComplexityGroup =
+ | DataComplexitySizeGroup
+ | DataComplexityAmbiguityGroup;
export type DataComplexityCatalog = {
- total: number | null;
+ score: number | null;
components: {
- [K in DataComplexityComponentId]: DataComplexitySubScore;
+ size: DataComplexitySizeGroup;
+ ambiguity: DataComplexityAmbiguityGroup;
};
};
export type DataComplexityScoresResponse = {
meta: {
formula_version: number;
+ format_version: number;
synonym_threshold: number;
calculated_at?: string;
embedding_model?: {
diff --git a/snowplow/iglu-client-embedded/schemas/com.metabase/data_complexity/jsonschema/1-0-0 b/snowplow/iglu-client-embedded/schemas/com.metabase/data_complexity/jsonschema/1-0-0
index cb13c6ed820..d866bcc0591 100644
--- a/snowplow/iglu-client-embedded/schemas/com.metabase/data_complexity/jsonschema/1-0-0
+++ b/snowplow/iglu-client-embedded/schemas/com.metabase/data_complexity/jsonschema/1-0-0
@@ -57,7 +57,7 @@
"maximum": 2147483647
},
"measurement": {
- "description": "Raw pre-score measurement (absent on aggregates; null on uncomputed leaves). Number, not integer, to future-proof.",
+ "description": "Raw pre-score measurement (absent on aggregates and on error leaves). Number, not integer, to future-proof.",
"type": [
"number",
"null"