Skip to content

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

Fix legacy semantic search startup validation (#78700)

Chris Trutera317fbf1b85a
diff --git a/src/metabase/search/core.clj b/src/metabase/search/core.clj
index adc0f3a6cf0..f7e18776952 100644
--- a/src/metabase/search/core.clj
+++ b/src/metabase/search/core.clj
@@ -1,7 +1,6 @@
(ns metabase.search.core
"NOT the API namespace for the search module!! See [[metabase.search]] instead."
(:require
- [clojure.string :as str]
[environ.core :as env]
[metabase.analytics-interface.core :as analytics]
[metabase.analytics.core :as analytics.core]
@@ -13,10 +12,10 @@
[metabase.search.ingestion :as search.ingestion]
[metabase.search.spec :as search.spec]
[metabase.search.util :as search.util]
+ [metabase.settings.core :as setting]
[metabase.startup.core :as startup]
[metabase.tracing.core :as tracing]
[metabase.util :as u]
- [metabase.util.i18n :refer [trs]]
[metabase.util.log :as log]
[potemkin :as p]))
@@ -101,36 +100,51 @@
(seq (search.engine/active-engines)))
(defn check-for-removed-env-vars!
- "Fail startup when the removed MB_SEMANTIC_SEARCH_ENABLED kill switch is still set, and would have been
+ "Fail startup when the removed MB_SEMANTIC_SEARCH_ENABLED kill switch is false, and would have been
required to disable the engine, naming the exact configuration change that keeps semantic search off.
- Otherwise just log a warning."
+ Otherwise log a warning, with migration guidance when a true value does not match the active engines."
[]
- ;; An empty value is "explicitly unset" per the usual env-var semantics, so only a non-blank value trips this.
- (when-not (str/blank? (env/env :mb-semantic-search-enabled))
- (let [engines (search.engine/supported-engines)
- semantic-default? (= :search.engine/semantic (first engines))
- semantic-additional? (contains? (set (search.engine/additional-engines)) :search.engine/semantic)
- fallback (when semantic-default? (second engines))
- ;; Each case is a complete sentence so translators can reorder it freely.
- detail (cond
- (and semantic-default? (not fallback))
- (trs "Semantic search is the only supported engine and cannot be disabled; remove MB_SEMANTIC_SEARCH_ENABLED.")
-
- (and fallback semantic-additional?)
- (trs "To keep semantic search off, set MB_SEARCH_ENGINE={0} and remove semantic from additional-search-engines, then remove MB_SEMANTIC_SEARCH_ENABLED."
- (name fallback))
-
- fallback
- (trs "To keep semantic search off, set MB_SEARCH_ENGINE={0}, then remove MB_SEMANTIC_SEARCH_ENABLED."
- (name fallback))
-
- semantic-additional?
- (trs "To keep semantic search off, remove semantic from additional-search-engines, then remove MB_SEMANTIC_SEARCH_ENABLED."))
- msg (str (trs "MB_SEMANTIC_SEARCH_ENABLED is no longer supported.") " "
- (or detail (trs "Remove it from your configuration.")))]
- (if detail
- (throw (ex-info msg {:env-var "MB_SEMANTIC_SEARCH_ENABLED"}))
- (log/warn msg)))))
+ (when-some [legacy-value (env/env :mb-semantic-search-enabled)]
+ (let [base-msg "MB_SEMANTIC_SEARCH_ENABLED is no longer supported."
+ remove-detail "Remove it from your configuration."]
+ ;; An empty value has no boolean meaning, but its presence still warrants removing the obsolete variable.
+ (if (empty? legacy-value)
+ (log/warn (str base-msg " " remove-detail))
+ (let [enabled? (setting/string->boolean legacy-value)
+ engines (search.engine/supported-engines)
+ semantic-default? (= :search.engine/semantic (first engines))
+ semantic-additional? (contains? (set (search.engine/additional-engines))
+ :search.engine/semantic)
+ semantic-supported? (contains? (set engines) :search.engine/semantic)
+ semantic-active? (or semantic-default? semantic-additional?)
+ fallback (when semantic-default? (second engines))
+ ;; Each case is a complete sentence so the remediation remains actionable.
+ error-detail (when-not enabled?
+ (cond
+ (and semantic-default? (not fallback))
+ "Semantic search is the only supported engine and cannot be disabled; remove MB_SEMANTIC_SEARCH_ENABLED."
+
+ (and fallback semantic-additional?)
+ (format "To keep semantic search off, set MB_SEARCH_ENGINE=%s and remove semantic from additional-search-engines, then remove MB_SEMANTIC_SEARCH_ENABLED."
+ (name fallback))
+
+ fallback
+ (format "To keep semantic search off, set MB_SEARCH_ENGINE=%s, then remove MB_SEMANTIC_SEARCH_ENABLED."
+ (name fallback))
+
+ semantic-additional?
+ "To keep semantic search off, remove semantic from additional-search-engines, then remove MB_SEMANTIC_SEARCH_ENABLED."))
+ warning-detail (when (and enabled? (not semantic-active?))
+ (if semantic-supported?
+ "To enable semantic search, set MB_SEARCH_ENGINE=semantic, then remove MB_SEMANTIC_SEARCH_ENABLED."
+ "Semantic search is not supported by this instance; remove MB_SEMANTIC_SEARCH_ENABLED."))
+ msg (str base-msg " "
+ (or error-detail
+ warning-detail
+ remove-detail))]
+ (if error-detail
+ (throw (ex-info msg {:env-var "MB_SEMANTIC_SEARCH_ENABLED"}))
+ (log/warn msg)))))))
(defmethod startup/def-startup-validation! ::check-for-removed-env-vars [_]
(check-for-removed-env-vars!))
diff --git a/test/metabase/search/engine_test.clj b/test/metabase/search/engine_test.clj
index 3e186b5c874..4c24a903fdd 100644
--- a/test/metabase/search/engine_test.clj
+++ b/test/metabase/search/engine_test.clj
@@ -51,55 +51,116 @@
(with-engines {:supported all-engines :configured :fulltext}
(is (= :search.engine/appdb (search.engine/default-engine))))))
-(deftest check-for-removed-env-vars-test
- (testing "the removed MB_SEMANTIC_SEARCH_ENABLED kill switch fails startup"
+(deftest check-for-removed-env-vars-false-default-test
+ (with-redefs [env/env {:mb-semantic-search-enabled "false"}]
+ (testing "the warning names the exact fallback engine when semantic is serving search"
+ (with-engines {:supported all-engines}
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"To keep semantic search off, set MB_SEARCH_ENGINE=appdb"
+ (search/check-for-removed-env-vars!)))))
+ (testing "the fallback follows precedence, not a hardcoded engine"
+ (with-engines {:supported #{:search.engine/semantic :search.engine/in-place}}
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"set MB_SEARCH_ENGINE=in-place"
+ (search/check-for-removed-env-vars!)))))
+ (testing "there is no fallback when semantic is the only supported engine"
+ (with-engines {:supported #{:search.engine/semantic}}
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"only supported engine and cannot be disabled"
+ (search/check-for-removed-env-vars!)))))))
+
+(deftest check-for-removed-env-vars-false-additional-test
+ (with-redefs [env/env {:mb-semantic-search-enabled "false"}]
+ (testing "the warning names both settings when semantic is the default and an additional engine"
+ (with-engines {:supported all-engines :additional ["semantic"]}
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"set MB_SEARCH_ENGINE=appdb and remove semantic from additional-search-engines"
+ (search/check-for-removed-env-vars!)))))
+ (testing "the warning points at additional-search-engines when it alone activates semantic"
+ (with-engines {:supported all-engines :configured :appdb :additional ["semantic"]}
+ (is (thrown-with-msg?
+ clojure.lang.ExceptionInfo
+ #"To keep semantic search off, remove semantic from additional-search-engines"
+ (search/check-for-removed-env-vars!)))))))
+
+(deftest check-for-removed-env-vars-false-inactive-test
+ (testing "startup proceeds with just a warning when another engine already serves search"
(with-redefs [env/env {:mb-semantic-search-enabled "false"}]
- (testing "naming the exact fallback engine when semantic is serving search"
- (with-engines {:supported all-engines}
- (is (thrown-with-msg?
- clojure.lang.ExceptionInfo
- #"To keep semantic search off, set MB_SEARCH_ENGINE=appdb"
- (search/check-for-removed-env-vars!))))
- (testing "the fallback follows precedence, not a hardcoded engine"
- (with-engines {:supported #{:search.engine/semantic :search.engine/in-place}}
- (is (thrown-with-msg?
- clojure.lang.ExceptionInfo
- #"set MB_SEARCH_ENGINE=in-place"
- (search/check-for-removed-env-vars!)))))
- (testing "when semantic is the only supported engine there is nothing to fall back to"
- (with-engines {:supported #{:search.engine/semantic}}
- (is (thrown-with-msg?
- clojure.lang.ExceptionInfo
- #"only supported engine and cannot be disabled"
- (search/check-for-removed-env-vars!))))))
- (testing "naming both settings when semantic is the default and also force-enabled as additional"
- (with-engines {:supported all-engines :additional ["semantic"]}
- (is (thrown-with-msg?
- clojure.lang.ExceptionInfo
- #"set MB_SEARCH_ENGINE=appdb and remove semantic from additional-search-engines"
- (search/check-for-removed-env-vars!)))))
- (testing "pointing at additional-search-engines when semantic is only force-enabled through it"
- (with-engines {:supported all-engines :configured :appdb :additional ["semantic"]}
- (is (thrown-with-msg?
- clojure.lang.ExceptionInfo
- #"To keep semantic search off, remove semantic from additional-search-engines"
- (search/check-for-removed-env-vars!)))))
- (testing "startup proceeds with just a warning when another engine already serves search"
- (with-engines {:supported #{:search.engine/appdb :search.engine/in-place}}
- (is (=? [{:level :warn
- :message "MB_SEMANTIC_SEARCH_ENABLED is no longer supported. Remove it from your configuration."}]
- (mt/with-log-messages-for-level [messages :warn]
- (search/check-for-removed-env-vars!)
- (messages))))))
- (testing "the check runs as a startup validation so a throw aborts the boot"
- (is (contains? (methods startup/def-startup-validation!)
- :metabase.search.core/check-for-removed-env-vars)))))
+ (with-engines {:supported #{:search.engine/appdb :search.engine/in-place}}
+ (is (=? [{:level :warn
+ :message "MB_SEMANTIC_SEARCH_ENABLED is no longer supported. Remove it from your configuration."}]
+ (mt/with-log-messages-for-level [messages :warn]
+ (search/check-for-removed-env-vars!)
+ (messages))))))))
+
+(deftest check-for-removed-env-vars-registration-test
+ (testing "the check runs as a startup validation so a throw aborts the boot"
+ (is (contains? (methods startup/def-startup-validation!)
+ :metabase.search.core/check-for-removed-env-vars))))
+
+(deftest check-for-removed-env-vars-presence-test
(testing "startup proceeds when the kill switch is absent"
(with-redefs [env/env {}]
(is (nil? (search/check-for-removed-env-vars!)))))
- (testing "an empty value counts as unset, not a leftover"
+ (testing "an explicitly empty value warns that the obsolete variable must be removed"
(with-redefs [env/env {:mb-semantic-search-enabled ""}]
- (is (nil? (search/check-for-removed-env-vars!))))))
+ (is (=? [{:level :warn
+ :message "MB_SEMANTIC_SEARCH_ENABLED is no longer supported. Remove it from your configuration."}]
+ (mt/with-log-messages-for-level [messages :warn]
+ (search/check-for-removed-env-vars!)
+ (messages)))))))
+
+(deftest check-for-removed-env-vars-true-test
+ (testing "startup proceeds with a warning when the kill switch is a double negative"
+ (doseq [value ["true" "TRUE"]]
+ (testing value
+ (with-redefs [env/env {:mb-semantic-search-enabled value}]
+ (testing "when semantic is the default engine"
+ (with-engines {:supported all-engines}
+ (is (=? [{:level :warn
+ :message "MB_SEMANTIC_SEARCH_ENABLED is no longer supported. Remove it from your configuration."}]
+ (mt/with-log-messages-for-level [messages :warn]
+ (search/check-for-removed-env-vars!)
+ (messages))))))
+ (testing "when semantic is an additional engine"
+ (with-engines {:supported all-engines :configured :appdb :additional ["semantic"]}
+ (is (=? [{:level :warn
+ :message "MB_SEMANTIC_SEARCH_ENABLED is no longer supported. Remove it from your configuration."}]
+ (mt/with-log-messages-for-level [messages :warn]
+ (search/check-for-removed-env-vars!)
+ (messages))))))))))
+ (testing "a true kill switch warns when semantic is not active"
+ (with-redefs [env/env {:mb-semantic-search-enabled "true"}]
+ (testing "with instructions to activate a supported semantic engine"
+ (with-engines {:supported all-engines :configured :appdb}
+ (is (=? [{:level :warn
+ :message (str "MB_SEMANTIC_SEARCH_ENABLED is no longer supported. "
+ "To enable semantic search, set MB_SEARCH_ENGINE=semantic, then remove "
+ "MB_SEMANTIC_SEARCH_ENABLED.")}]
+ (mt/with-log-messages-for-level [messages :warn]
+ (search/check-for-removed-env-vars!)
+ (messages))))))
+ (testing "without activation instructions when semantic is unsupported"
+ (with-engines {:supported #{:search.engine/appdb :search.engine/in-place}}
+ (is (=? [{:level :warn
+ :message (str "MB_SEMANTIC_SEARCH_ENABLED is no longer supported. "
+ "Semantic search is not supported by this instance; "
+ "remove MB_SEMANTIC_SEARCH_ENABLED.")}]
+ (mt/with-log-messages-for-level [messages :warn]
+ (search/check-for-removed-env-vars!)
+ (messages)))))))))
+
+(deftest check-for-removed-env-vars-invalid-test
+ (testing "an unexpected value fails with the legacy boolean validation message"
+ (with-redefs [env/env {:mb-semantic-search-enabled "unsupported"}]
+ (is (thrown-with-msg?
+ Exception
+ #"Invalid value for string: must be either"
+ (search/check-for-removed-env-vars!))))))
(deftest search-engine-setting-test
(testing "the setting computes the resolved engine when no value is configured"