Skip to content

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

[GHY-4523] Add remote sync support for glossary (#82390)

Tyler Plude69b65837bb10
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index 964d6753907..2e8701b2de9 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -1106,6 +1106,7 @@
events
lib.schema
models
+ remote-sync
util}
:model-exports #{:model/Glossary}
:model-imports #{:model/User}}
@@ -4103,6 +4104,7 @@
:model/Document
:model/Field
:model/FieldUserSettings
+ :model/Glossary
:model/Measure
:model/NativeQuerySnippet
:model/PythonLibrary
diff --git a/e2e/support/assets/example_synced_library/collections/main/library.yaml b/e2e/support/assets/example_synced_library/collections/main/library.yaml
new file mode 100644
index 00000000000..ff9dcac868f
--- /dev/null
+++ b/e2e/support/assets/example_synced_library/collections/main/library.yaml
@@ -0,0 +1,10 @@
+name: Library
+entity_id: librarylibrarylibrary
+slug: library
+created_at: '2026-09-11T00:00:00Z'
+type: library
+serdes/meta:
+- id: librarylibrarylibrary
+ label: library
+ model: Collection
+is_remote_synced: true
diff --git a/e2e/support/assets/example_synced_library/collections/main/library/data.yaml b/e2e/support/assets/example_synced_library/collections/main/library/data.yaml
new file mode 100644
index 00000000000..6fd33f99caa
--- /dev/null
+++ b/e2e/support/assets/example_synced_library/collections/main/library/data.yaml
@@ -0,0 +1,11 @@
+name: Data
+entity_id: librarylibrarydatadat
+slug: data
+created_at: '2026-09-11T00:00:00Z'
+type: library-data
+parent_id: librarylibrarylibrary
+serdes/meta:
+- id: librarylibrarydatadat
+ label: data
+ model: Collection
+is_remote_synced: true
diff --git a/e2e/support/assets/example_synced_library/collections/main/library/metrics.yaml b/e2e/support/assets/example_synced_library/collections/main/library/metrics.yaml
new file mode 100644
index 00000000000..fcc308457f7
--- /dev/null
+++ b/e2e/support/assets/example_synced_library/collections/main/library/metrics.yaml
@@ -0,0 +1,11 @@
+name: Metrics
+entity_id: librarylibrarymetrics
+slug: metrics
+created_at: '2026-09-11T00:00:00Z'
+type: library-metrics
+parent_id: librarylibrarylibrary
+serdes/meta:
+- id: librarylibrarymetrics
+ label: metrics
+ model: Collection
+is_remote_synced: true
diff --git a/e2e/support/assets/example_synced_library/glossary/arr.yaml b/e2e/support/assets/example_synced_library/glossary/arr.yaml
new file mode 100644
index 00000000000..d847ac3e9c8
--- /dev/null
+++ b/e2e/support/assets/example_synced_library/glossary/arr.yaml
@@ -0,0 +1,8 @@
+created_at: '2026-09-11T00:00:00Z'
+creator_id: [email protected]
+definition: Annual recurring revenue
+entity_id: glossaryfixturearr001
+term: ARR
+serdes/meta:
+- id: glossaryfixturearr001
+ model: Glossary
diff --git a/e2e/support/helpers/e2e-remote-sync-helpers.ts b/e2e/support/helpers/e2e-remote-sync-helpers.ts
index 269e32e213e..f345dcf9738 100644
--- a/e2e/support/helpers/e2e-remote-sync-helpers.ts
+++ b/e2e/support/helpers/e2e-remote-sync-helpers.ts
@@ -19,6 +19,8 @@ export const SYNCED_COLLECTION_FIXTURE_PATH =
export const SYNCED_TRANSFORMS_COLLECTION_FIXTURE_PATH =
Cypress.config("projectRoot") +
"/e2e/support/assets/example_synced_transforms_collection";
+export const SYNCED_LIBRARY_FIXTURE_PATH =
+ Cypress.config("projectRoot") + "/e2e/support/assets/example_synced_library";
// Copy the sample synced collection from the fixture folder to the working directory
export const copySyncedCollectionFixture = () => {
@@ -34,6 +36,13 @@ export const copySyncedTransformsCollectionFixture = () => {
destination: LOCAL_GIT_PATH,
});
};
+// Copy the sample remote-synced Library (with one glossary entry) from the fixture folder to the working directory
+export const copySyncedLibraryFixture = () => {
+ cy.task("copyDirectory", {
+ source: SYNCED_LIBRARY_FIXTURE_PATH,
+ destination: LOCAL_GIT_PATH,
+ });
+};
export const checkoutSyncedCollectionBranch = (branch: string) => {
cy.exec("git -C " + LOCAL_GIT_PATH + ` checkout -b '${branch}'`);
diff --git a/e2e/test/scenarios/admin/remote-sync.cy.spec.ts b/e2e/test/scenarios/admin/remote-sync.cy.spec.ts
index cd8bfe4e4db..31085f93327 100644
--- a/e2e/test/scenarios/admin/remote-sync.cy.spec.ts
+++ b/e2e/test/scenarios/admin/remote-sync.cy.spec.ts
@@ -1,3 +1,5 @@
+import yaml from "js-yaml";
+
import { WRITABLE_DB_ID } from "e2e/support/cypress_data";
import { SAMPLE_DATABASE } from "e2e/support/cypress_sample_database";
import {
@@ -1227,6 +1229,129 @@ describe("Remote Sync", () => {
});
});
});
+
+ describe("glossary", () => {
+ const GLOSSARY_TERM = "ARR";
+ const GLOSSARY_DEFINITION = "Annual recurring revenue";
+
+ const visitDataStudioGlossary = () => {
+ H.DataModel.visitDataStudio();
+ glossaryTab().click();
+ cy.findByRole("heading", { name: "Glossary" }).should("be.visible");
+ };
+
+ const glossaryTab = () => H.DataStudio.nav().findByLabelText("Glossary");
+
+ describe("read-write mode", () => {
+ beforeEach(() => {
+ setup();
+ });
+
+ it("flags a new term on the Glossary tab and pushes it to the repository", () => {
+ // Glossary entries ride with the Library, so sync the Library rather than a plain collection.
+ H.createLibrary().then(({ body: library }) => {
+ H.configureGit("read-write", LOCAL_GIT_URL, { [library.id]: true });
+ });
+
+ visitDataStudioGlossary();
+ cy.findByRole("button", { name: /new term/i }).click();
+ cy.findByPlaceholderText(/boat/i).type(GLOSSARY_TERM);
+ cy.findByPlaceholderText(/a small vessel.*/i).type(GLOSSARY_DEFINITION);
+ cy.findByLabelText("Save").click();
+ cy.get("table").findByText(GLOSSARY_TERM).should("be.visible");
+
+ cy.log("The Glossary tab shows unsynced changes");
+ glossaryTab().findByTestId("remote-sync-status").should("be.visible");
+
+ H.clickPushOption();
+ H.modal()
+ .button(/Push changes/)
+ .click();
+ H.waitForTask({ taskName: "export" });
+
+ cy.log("The badge clears once the term is pushed");
+ glossaryTab().findByTestId("remote-sync-status").should("not.exist");
+
+ cy.log("The term is serialized under glossary/ in the repository");
+ H.wrapSyncedCollectionFiles();
+ cy.get("@syncedCollectionFiles").then((files) => {
+ // Unjustified type cast. FIXME
+ const glossaryFile = (files as unknown as string[]).find((file) =>
+ file.includes("glossary/"),
+ );
+ expect(glossaryFile).to.match(/glossary\/arr\.yaml$/);
+
+ cy.readFile(`${H.LOCAL_GIT_PATH}/${glossaryFile}`).then((str) => {
+ // Unjustified type cast. FIXME
+ const doc = yaml.load(str) as Record<string, unknown>;
+ expect(doc.term).to.equal(GLOSSARY_TERM);
+ expect(doc.definition).to.equal(GLOSSARY_DEFINITION);
+ expect(doc.entity_id).to.be.a("string").with.lengthOf(21);
+ });
+ });
+ });
+ });
+
+ describe("read-only mode", () => {
+ beforeEach(() => {
+ setup();
+ // The fixture carries the Library (matching the ids createLibrary assigns) with is_remote_synced set,
+ // so the pull both loads the term and locks the glossary.
+ H.createLibrary();
+ H.copySyncedLibraryFixture();
+ H.commitToRepo();
+ H.configureGitAndPullChanges("read-only");
+ });
+
+ it("lists pulled terms and locks editing", () => {
+ visitDataStudioGlossary();
+
+ cy.get("table").within(() => {
+ cy.findByText(GLOSSARY_TERM).should("be.visible");
+ cy.findByText(GLOSSARY_DEFINITION).should("be.visible");
+ cy.findByLabelText("Delete").should("not.exist");
+ });
+ cy.findByRole("button", { name: /new term/i }).should("not.exist");
+
+ cy.log("Clicking a term does not open the inline editor");
+ cy.get("table").findByText(GLOSSARY_TERM).click();
+ cy.findByPlaceholderText(/boat/i).should("not.exist");
+
+ cy.log(
+ "The API reports the glossary as not writable and rejects writes",
+ );
+ cy.request("GET", "/api/glossary").then(({ body }) => {
+ expect(body.can_write).to.equal(false);
+ const [entry] = body.data;
+ expect(entry.term).to.equal(GLOSSARY_TERM);
+
+ cy.request({
+ method: "POST",
+ url: "/api/glossary",
+ body: { term: "MRR", definition: "Monthly recurring revenue" },
+ failOnStatusCode: false,
+ })
+ .its("status")
+ .should("eq", 403);
+ cy.request({
+ method: "PUT",
+ url: `/api/glossary/${entry.id}`,
+ body: { term: GLOSSARY_TERM, definition: "changed" },
+ failOnStatusCode: false,
+ })
+ .its("status")
+ .should("eq", 403);
+ cy.request({
+ method: "DELETE",
+ url: `/api/glossary/${entry.id}`,
+ failOnStatusCode: false,
+ })
+ .its("status")
+ .should("eq", 403);
+ });
+ });
+ });
+ });
});
const ensureSyncedCollectionIsVisible = () => {
diff --git a/e2e/test/scenarios/data-reference/glossary.cy.spec.ts b/e2e/test/scenarios/data-reference/glossary.cy.spec.ts
index 751c3e3f397..1650028e5e5 100644
--- a/e2e/test/scenarios/data-reference/glossary.cy.spec.ts
+++ b/e2e/test/scenarios/data-reference/glossary.cy.spec.ts
@@ -108,6 +108,7 @@ describe("data reference > glossary", () => {
{ id: 1, term: "Alpha", definition: "First" },
{ id: 2, term: "Beta", definition: "Second" },
],
+ can_write: true,
},
}).as("getGlossary");
diff --git a/enterprise/backend/src/metabase_enterprise/remote_sync/db.clj b/enterprise/backend/src/metabase_enterprise/remote_sync/db.clj
index 796e3fadc14..cbe6924d7eb 100644
--- a/enterprise/backend/src/metabase_enterprise/remote_sync/db.clj
+++ b/enterprise/backend/src/metabase_enterprise/remote_sync/db.clj
@@ -59,6 +59,13 @@
conditions :- Conditions]
(apply t2/select-fn-set :id model-key (mapcat identity conditions)))
+(mu/defn entity-id-where :- [:maybe :string]
+ "The `:entity_id` of the instance of `model-key` whose `column` equals `value`, or nil."
+ [model-key :- :keyword
+ column :- [:enum :name :term]
+ value :- :string]
+ (t2/select-one-fn :entity_id model-key column value))
+
(mu/defn count-where
"The number of instances of `model-key` matching `conditions` (a map of column to value or Toucan 2
operator-vector value, or nil for every instance)."
@@ -125,13 +132,14 @@
(t2/count model-key {:where (unsynced-instance-expr model-key model-type removal-opts)}))
(mu/defn unsynced-instance-names
- "Up to `limit` names of the rows [[unsynced-instance-count]] counts."
+ "Up to `limit` values of `name-col` from the rows [[unsynced-instance-count]] counts."
[model-key :- :keyword
model-type :- :string
+ name-col :- [:enum :name :term]
removal-opts :- RemovalOpts
limit :- ms/PositiveInt]
- (t2/select-fn-vec :name model-key {:where (unsynced-instance-expr model-key model-type removal-opts)
- :limit limit}))
+ (t2/select-fn-vec name-col model-key {:where (unsynced-instance-expr model-key model-type removal-opts)
+ :limit limit}))
(mu/defn instance
"The instance of `model` with `id`, or nil."
@@ -294,6 +302,21 @@
[]
(t2/select [:model/NativeQuerySnippet :id :name :collection_id]))
+(mu/defn glossary-entries
+ "The `:id` and `:term` of every Glossary entry."
+ []
+ (t2/select [:model/Glossary :id :term]))
+
+(mu/defn untracked-glossary-entries
+ "The `:id` and `:term` of every Glossary entry with no RemoteSyncObject."
+ []
+ (t2/select [:model/Glossary :id :term]
+ {:where [:not [:exists ^:allow-subquery {:select [1]
+ :from [:remote_sync_object]
+ :where [:and
+ [:= :remote_sync_object.model_type "Glossary"]
+ [:= :remote_sync_object.model_id :glossary.id]]}]]}))
+
(defn- subtree-expr
"Matches `collections` and all of their descendants."
[collections]
diff --git a/enterprise/backend/src/metabase_enterprise/remote_sync/events.clj b/enterprise/backend/src/metabase_enterprise/remote_sync/events.clj
index 88031476314..624c94efe21 100644
--- a/enterprise/backend/src/metabase_enterprise/remote_sync/events.clj
+++ b/enterprise/backend/src/metabase_enterprise/remote_sync/events.clj
@@ -14,7 +14,7 @@
- Table and TableUserSettings, which also carries a Field's own edits (when published in a remote-synced collection)
- Segment, Measure (when belonging to a published table in a remote-synced collection)
- Transform, TransformTag, transforms-namespace Collections (when remote-sync-transforms setting is enabled)
- - NativeQuerySnippet, snippets-namespace Collections (when Library is remote-synced)"
+ - NativeQuerySnippet, snippets-namespace Collections, Glossary (when Library is remote-synced)"
(:require
[java-time.api :as t]
[metabase-enterprise.remote-sync.db :as remote-sync.db]
@@ -26,8 +26,18 @@
[methodical.core :as methodical]
[toucan2.core :as t2]))
-(defn enable-snippet-tracking!
- "Mark all existing snippets and snippets-namespace collections as 'create' for initial sync."
+(defn- glossary-tracking-rows
+ "A 'create' ledger row for each of the glossary `entries`."
+ [entries timestamp]
+ (for [entry entries]
+ {:model_type "Glossary"
+ :model_id (:id entry)
+ :model_name (:term entry)
+ :status "create"
+ :status_changed_at timestamp}))
+
+(defn enable-library-tracking!
+ "Mark all existing snippets, snippets-namespace collections, and glossary entries as 'create' for initial sync."
[]
(let [timestamp (t/offset-date-time)
rows (concat
@@ -43,15 +53,26 @@
:model_name (:name snippet)
:model_collection_id (:collection_id snippet)
:status "create"
- :status_changed_at timestamp}))]
+ :status_changed_at timestamp})
+ (glossary-tracking-rows (remote-sync.db/glossary-entries) timestamp))]
(when (seq rows)
(remote-sync.db/insert-rsos! rows))))
-(defn disable-snippet-tracking!
- "Remove all snippet-related tracking entries."
+(defn backfill-glossary-tracking!
+ "Insert a 'create' ledger row for every glossary entry that has none, so an instance upgraded with the Library
+ already synced still pushes its entries. Returns the number of rows inserted."
+ []
+ (let [rows (vec (glossary-tracking-rows (remote-sync.db/untracked-glossary-entries) (t/offset-date-time)))]
+ (when (seq rows)
+ (remote-sync.db/insert-rsos! rows))
+ (count rows)))
+
+(defn disable-library-tracking!
+ "Remove all snippet, snippets-namespace collection, and glossary tracking entries."
[]
(let [snippet-coll-ids (remote-sync.db/snippet-collection-ids)]
(remote-sync.db/delete-rsos-of-type! "NativeQuerySnippet")
+ (remote-sync.db/delete-rsos-of-type! "Glossary")
(when (seq snippet-coll-ids)
(remote-sync.db/delete-rsos-of-models! "Collection" snippet-coll-ids))))
@@ -262,19 +283,20 @@
(remote-sync.db/collection-name-and-id id))
(defn- handle-library-sync-status-change!
- "When the Library collection's is_remote_synced status changes, trigger snippet sync tracking.
- This ensures all snippets are tracked/untracked when Library sync is enabled/disabled."
+ "When the Library collection's is_remote_synced status changes, trigger Library content sync tracking.
+ This ensures all snippets and glossary entries are tracked/untracked when Library sync is enabled/disabled."
[is-now-synced?]
- (let [snippets-already-tracked? (remote-sync.db/rso-of-type-exists? "NativeQuerySnippet")]
+ (let [library-already-tracked? (or (remote-sync.db/rso-of-type-exists? "NativeQuerySnippet")
+ (remote-sync.db/rso-of-type-exists? "Glossary"))]
(cond
- (and is-now-synced? (not snippets-already-tracked?))
+ (and is-now-synced? (not library-already-tracked?))
(do
- (log/info "Library collection became remote-synced, enabling snippet sync tracking")
- (enable-snippet-tracking!))
- (and (not is-now-synced?) snippets-already-tracked?)
+ (log/info "Library collection became remote-synced, enabling Library content sync tracking")
+ (enable-library-tracking!))
+ (and (not is-now-synced?) library-already-tracked?)
(do
- (log/info "Library collection is no longer remote-synced, disabling snippet sync tracking")
- (disable-snippet-tracking!)))))
+ (log/info "Library collection is no longer remote-synced, disabling Library content sync tracking")
+ (disable-library-tracking!)))))
(methodical/defmethod events/publish-event! ::collection-change-event
[topic event]
diff --git a/enterprise/backend/src/metabase_enterprise/remote_sync/impl.clj b/enterprise/backend/src/metabase_enterprise/remote_sync/impl.clj
index e2907f39260..0da994890c1 100644
--- a/enterprise/backend/src/metabase_enterprise/remote_sync/impl.clj
+++ b/enterprise/backend/src/metabase_enterprise/remote_sync/impl.clj
@@ -202,7 +202,7 @@
- :*-conflict (deletion) - import lacks transforms/tags/libraries that exist locally and unsynced (GHY-3900)"
[ingestable first-import?]
(let [ingest-list (serialization/ingest-list ingestable)
- imported-data (spec/extract-imported-entities ingest-list)
+ imported-data (spec/extract-imported-entities ingest-list #(serialization/ingest-one ingestable %))
models-present (spec/models-in-import ingest-list)
;; Extract namespace info from imported Collection entities
import-ns-info
@@ -1020,7 +1020,7 @@
[]
(cond-> #{}
(not (settings/remote-sync-transforms)) (into ["transforms" "python-libraries" "python_libraries"])
- (not (settings/library-is-remote-synced?)) (conj "snippets")))
+ (not (settings/library-is-remote-synced?)) (into ["snippets" "glossary"])))
(defn- stage-write [commit opts [row entity]]
(let [path (or (:file_path row) (source/entity->path opts entity))
diff --git a/enterprise/backend/src/metabase_enterprise/remote_sync/init.clj b/enterprise/backend/src/metabase_enterprise/remote_sync/init.clj
index 0ba7cc433af..be26ebd3f12 100644
--- a/enterprise/backend/src/metabase_enterprise/remote_sync/init.clj
+++ b/enterprise/backend/src/metabase_enterprise/remote_sync/init.clj
@@ -2,7 +2,7 @@
(:require
[clojure.java.io :as io]
[clojure.string :as str]
- [metabase-enterprise.remote-sync.events]
+ [metabase-enterprise.remote-sync.events :as events]
[metabase-enterprise.remote-sync.impl :as impl]
[metabase-enterprise.remote-sync.models.remote-sync-object :as remote-sync.object]
[metabase-enterprise.remote-sync.settings :as settings]
@@ -52,6 +52,13 @@
(impl/publish-sync-event! :event/remote-sync-import task-id
{:branch branch :auto true} nil)))
(throw (ex-info "Remote sync is enabled with read-only type, but there are unpublished changes. To force an overwrite, set `MB_REMOTE_SYNC_ALLOW=overwrite-unpublished`" {}))))))
+ ;; Read-only instances are skipped: a dirty ledger would fail the check above, and their next full pull
+ ;; rebuilds the ledger anyway.
+ (when (and (= :read-write (settings/remote-sync-type))
+ (settings/library-is-remote-synced?))
+ (let [n (events/backfill-glossary-tracking!)]
+ (when (pos? n)
+ (log/infof "Tracking %d existing glossary entries for remote sync" n))))
(when-not (collection/has-remote-synced-collection?)
(if (nil? (settings/remote-sync-branch))
(log/warn "Remote sync is enabled but no remote-sync branch is set. Cannot do initial import.")
diff --git a/enterprise/backend/src/metabase_enterprise/remote_sync/models/remote_sync_task.clj b/enterprise/backend/src/metabase_enterprise/remote_sync/models/remote_sync_task.clj
index 07fb43303d4..70f8e5dab7c 100644
--- a/enterprise/backend/src/metabase_enterprise/remote_sync/models/remote_sync_task.clj
+++ b/enterprise/backend/src/metabase_enterprise/remote_sync/models/remote_sync_task.clj
@@ -255,13 +255,13 @@
(defn conflict-sync-task!
"Marks a sync task as having conflicts.
- Takes the ID of the sync task and a collection of conflicts (vector of strings).
- Conflicts are automatically serialized to JSON via the model transform.
+ Takes the ID of the sync task and a collection of conflict category names (`import!` reports them as a
+ set). Conflicts are automatically serialized to JSON via the model transform.
Returns the number of rows updated (should be 1 if successful)."
[task-id conflicts]
(remote-sync.db/end-task! task-id
- {:conflicts conflicts}))
+ {:conflicts (vec conflicts)}))
;;; ------------------------------------------- Hydration -------------------------------------------
diff --git a/enterprise/backend/src/metabase_enterprise/remote_sync/spec.clj b/enterprise/backend/src/metabase_enterprise/remote_sync/spec.clj
index 7cd9839ab5d..c9213f189bd 100644
--- a/enterprise/backend/src/metabase_enterprise/remote_sync/spec.clj
+++ b/enterprise/backend/src/metabase_enterprise/remote_sync/spec.clj
@@ -73,7 +73,7 @@
- :export-scope - Export scope for query-export-roots:
:root-collections - Query root-level remote-synced + namespace collections (Collection)
:root-only - Query root instances with collection_id = nil (Transform)
- :all - Query all instances (TransformTag, PythonLibrary, NativeQuerySnippet)
+ :all - Query all instances (TransformTag, PythonLibrary, NativeQuerySnippet, Glossary)
nil/:derived - No root query; derived from other models via serdes/descendants
- :enabled? - true, or setting keyword (e.g., :remote-sync-transforms, :library-synced).
When :library-synced, uses the library-is-remote-synced? setting."
@@ -146,6 +146,22 @@
:export-scope :all ; export all snippets
:enabled? :library-synced}
+ :model/Glossary
+ {:model-type "Glossary"
+ :model-key :model/Glossary
+ :identity :entity-id
+ :events {:prefix :event/glossary
+ :types [:create :update :delete]}
+ :eligibility {:type :library-synced} ; sync every glossary entry when Library is remote-synced
+ :archived-key nil
+ :tracking {:select-fields [:term]
+ :field-mappings {:model_name :term}}
+ :removal {:statuses #{"removed" "delete"}} ; no scope-key = global deletion
+ :export-scope :all ; export all glossary entries
+ :enabled? :library-synced
+ ;; files exported before `entity_id` existed are keyed by term; resolve those paths through load-find-local
+ :natural-key-paths? true}
+
:model/Timeline
{:model-type "Timeline"
:model-key :model/Timeline
@@ -442,6 +458,14 @@
:library-synced "Snippets"
(str/capitalize (name setting-kw))))
+(defn- setting->content-label
+ "Describes the content a feature setting governs, for conflict messages. The Library groups several models
+ under one category, so name them rather than the category."
+ [setting-kw]
+ (case setting-kw
+ :library-synced "Library content (snippets, glossary)"
+ (setting->category setting-kw)))
+
(defn- setting->namespace
"Converts a setting keyword to the corresponding collection namespace keyword, or nil."
[setting-kw]
@@ -533,11 +557,11 @@
(and feature-namespace
(contains? import-namespace-collections (name feature-namespace))))
:when (has-unsynced-entities-for-feature? specs-for-feature)
- :let [category (setting->category setting-kw)]]
+ :let [category (setting->category setting-kw)
+ label (setting->content-label setting-kw)]]
{:type (keyword (str (u/lower-case-en category) "-conflict"))
:category category
- :message (format "Import contains %s but local instance has unsynced %s"
- category category)}))))
+ :message (format "Import contains %s but local instance has unsynced %s" label label)}))))
(defn check-namespace-collection-conflicts
"Checks if import contains namespace collections (transforms/snippets) that conflict with local
@@ -683,14 +707,16 @@
;; unsynced rows the import would delete. Done in SQL so we never materialize a whole
;; collection's worth of rows just to count/sample them.
opts (removal-opts spec synced-collection-ids imported-ids)
- n (remote-sync.db/unsynced-instance-count model-key model-type opts)]
+ n (remote-sync.db/unsynced-instance-count model-key model-type opts)
+ name-col (get-in spec [:tracking :field-mappings :model_name])]
:when (pos? n)]
{:type (keyword (str (u/lower-case-en model-type) "-deletion-conflict"))
:category model-type
:model model-type
:count n
;; A bounded sample of names for the UI; :count above is the true total.
- :names (remote-sync.db/unsynced-instance-names model-key model-type opts max-conflict-names)
+ :names (remote-sync.db/unsynced-instance-names model-key model-type name-col opts
+ max-conflict-names)
:message (format "Import would delete %d unsynced local %s %s"
n model-type (if (= 1 n) "entity" "entities"))})))))
@@ -885,17 +911,37 @@
"Extracts identity data from a serdes path based on the spec's identity strategy. For entity-id
and hybrid models, returns the entity_id string from the last path element. For path-based models
like Table and Field, returns a map with database, schema, and table/field names that can be used
- to look up the entity."
- {:arglists '([spec serdes-path])}
- (fn [spec _path] (:identity spec))
+ to look up the entity. A spec with `:natural-key-paths?` may also be keyed on a natural key (files
+ exported before the model had an entity_id); its paths are resolved through `serdes/load-find-local`, and
+ through the entity's natural key when `ingest-one` (path -> ingested entity, or nil) is given."
+ {:arglists '([spec serdes-path ingest-one])}
+ (fn [spec _path _ingest-one] (:identity spec))
:hierarchy #'serdes-path-identity-hierarchy)
+(defn- natural-key-entity-id
+ "The entity_id of the local row whose natural-key column (the spec's tracked name column) equals `ingested`'s,
+ or nil."
+ [{:keys [model-key] :as spec} ingested]
+ (let [column (get-in spec [:tracking :field-mappings :model_name])]
+ (when-some [value (get ingested column)]
+ (remote-sync.db/entity-id-where model-key column value))))
+
(defmethod extract-identity-from-serdes-path ::entity-id-extractor
- [_ serdes-path]
- (:id (last serdes-path)))
+ [{:keys [natural-key-paths?] :as spec} serdes-path ingest-one]
+ (let [id (:id (last serdes-path))]
+ (if natural-key-paths?
+ ;; The path id may be a natural key (a glossary term, before `entity_id` existed) naming whichever local row
+ ;; the loader matches it to, so use that row's entity_id. Before the load there may be no row with that id
+ ;; yet; the loader then matches the entity on its natural key, so resolve the same way when the entity can
+ ;; be read. Failing both, the raw id is kept, since it matches no local row (harmless to the removal
+ ;; anti-join) and still counts as an imported entity.
+ (or (:entity_id (serdes/load-find-local serdes-path))
+ (when ingest-one (natural-key-entity-id spec (ingest-one serdes-path)))
+ id)
+ id)))
(defmethod extract-identity-from-serdes-path :path
- [_ serdes-path]
+ [_ serdes-path _ingest-one]
(let [path-map (into {} (map (fn [elem] [(keyword (u/lower-case-en (:model elem))) (:id elem)]) serdes-path))]
(cond-> {}
(contains? path-map :database) (assoc :db_name (:database path-map))
@@ -904,34 +950,39 @@
(contains? path-map :field) (assoc :field_name (:field path-map)))))
(defmethod extract-identity-from-serdes-path :default
- [_ _]
+ [_ _ _]
nil)
(defn extract-imported-entities
"Processes serdes paths from an import and extracts entity identities grouped by how they should be looked up.
Returns a map with :by-entity-id containing entity_ids grouped by model type, and :by-path containing
- path lookup maps for models like Table and Field that use path-based identity."
- [seen-paths]
- (reduce
- (fn [acc path]
- (let [model-type (-> path last :model)]
- (if-let [spec (spec-for-model-type model-type)]
- (let [identity-type (:identity spec)
- identity-data (extract-identity-from-serdes-path spec path)]
- (if identity-data
- (case identity-type
- (:entity-id :hybrid)
- (update-in acc [:by-entity-id model-type] (fnil conj #{}) identity-data)
-
- :path
- (update-in acc [:by-path (:model-key spec)] (fnil conj []) identity-data)
-
- acc)
- acc))
- acc)))
- {:by-entity-id {}
- :by-path {}}
- seen-paths))
+ path lookup maps for models like Table and Field that use path-based identity.
+
+ `ingest-one` (path -> ingested entity) is for the pre-load conflict check: a `:natural-key-paths?` path whose
+ id matches no local row yet resolves to the row the loader will match on the entity's natural key."
+ ([seen-paths]
+ (extract-imported-entities seen-paths nil))
+ ([seen-paths ingest-one]
+ (reduce
+ (fn [acc path]
+ (let [model-type (-> path last :model)]
+ (if-let [spec (spec-for-model-type model-type)]
+ (let [identity-type (:identity spec)
+ identity-data (extract-identity-from-serdes-path spec path ingest-one)]
+ (if identity-data
+ (case identity-type
+ (:entity-id :hybrid)
+ (update-in acc [:by-entity-id model-type] (fnil conj #{}) identity-data)
+
+ :path
+ (update-in acc [:by-path (:model-key spec)] (fnil conj []) identity-data)
+
+ acc)
+ acc))
+ acc)))
+ {:by-entity-id {}
+ :by-path {}}
+ seen-paths)))
;;; -------------------------------------------- Event Helper Functions ------------------------------------------------
diff --git a/enterprise/backend/test/metabase_enterprise/remote_sync/content_hash_test.clj b/enterprise/backend/test/metabase_enterprise/remote_sync/content_hash_test.clj
index c59b149cf51..cd680f4d226 100644
--- a/enterprise/backend/test/metabase_enterprise/remote_sync/content_hash_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/remote_sync/content_hash_test.clj
@@ -81,6 +81,12 @@
:model/NativeQuerySnippet snip {:name "Snip" :content "SELECT 1" :collection_id (:id sc)}]
(is (= "synced" (noop-update-status! "NativeQuerySnippet" (:id snip) :event/snippet-update snip)))))))
+(deftest glossary-noop-update-stays-synced-test
+ (testing "A no-op Glossary update keeps it synced when the Library is synced"
+ (with-library-synced
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (is (= "synced" (noop-update-status! "Glossary" (:id entry) :event/glossary-update entry)))))))
+
(deftest collection-noop-update-stays-synced-test
(testing "A no-op Collection update keeps it synced (GHY-3933)"
(mt/with-temp [:model/Collection coll {:is_remote_synced true :name "RS"}]
@@ -415,6 +421,27 @@
(when payload-fn (payload-fn entity))))
(:status (t2/select-one :model/RemoteSyncObject :model_type model-type :model_id model-id))))))
+(deftest glossary-import-then-noop-stays-synced-test
+ (testing "After a real import, a no-op Glossary update stays synced"
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary :model/Collection]
+ ;; The snapshot carries the Library as a read-write instance exports it, so the Library stays synced
+ ;; through the import and the Glossary spec is enabled when the ledger is rebuilt.
+ (t2/delete! :model/Collection :entity_id collection/library-entity-id)
+ (let [eid "test-glossary-xxxxxxx"
+ files {"main" {"collections/library/library.yaml"
+ (test-helpers/generate-collection-yaml collection/library-entity-id "Library"
+ :type "library" :is-remote-synced true)
+ "collections/main/test_coll/test_coll.yaml"
+ (test-helpers/generate-collection-yaml "test-collection-1xxxx" "Test Collection")
+ "glossary/arr.yaml"
+ (test-helpers/generate-glossary-yaml eid "ARR" "Annual recurring revenue")}}]
+ (is (= "synced"
+ (import-then-noop-status!
+ files "Glossary"
+ #(t2/select-one :model/Glossary :entity_id eid)
+ :event/glossary-update))))))))
+
(deftest transform-import-then-noop-stays-synced-test
(testing "After a real import, a no-op Transform update stays synced (GHY-3933)"
(mt/with-premium-features #{:transforms-basic}
diff --git a/enterprise/backend/test/metabase_enterprise/remote_sync/glossary_test.clj b/enterprise/backend/test/metabase_enterprise/remote_sync/glossary_test.clj
new file mode 100644
index 00000000000..bb67069a1ba
--- /dev/null
+++ b/enterprise/backend/test/metabase_enterprise/remote_sync/glossary_test.clj
@@ -0,0 +1,492 @@
+(ns metabase-enterprise.remote-sync.glossary-test
+ "Glossary entries are synced globally when the Library collection is remote-synced, like snippets."
+ (:require
+ [clojure.string :as str]
+ [clojure.test :refer :all]
+ [java-time.api :as t]
+ [metabase-enterprise.remote-sync.events :as rs-events]
+ [metabase-enterprise.remote-sync.impl :as impl]
+ [metabase-enterprise.remote-sync.models.remote-sync-object :as sync-object]
+ [metabase-enterprise.remote-sync.source :as source]
+ [metabase-enterprise.remote-sync.source.protocol :as source.p]
+ [metabase-enterprise.remote-sync.spec :as spec]
+ [metabase-enterprise.remote-sync.test-helpers :as test-helpers]
+ [metabase.collections.models.collection :as collection]
+ [metabase.collections.test-utils :as collections.tu]
+ [metabase.events.core :as events]
+ [metabase.glossary.core :as glossary.core]
+ [metabase.search.core :as search]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util :as u]
+ [metabase.util.yaml :as yaml]
+ [toucan2.core :as t2]))
+
+(use-fixtures :once (fixtures/initialize :db))
+
+(defn- clean-remote-sync-state
+ "Test fixture that cleans up remote sync state before and after each test."
+ [f]
+ (try
+ (t2/delete! :model/RemoteSyncObject)
+ (f)
+ (finally
+ (t2/delete! :model/RemoteSyncObject))))
+
+(use-fixtures :each (fn [f]
+ (mt/with-dynamic-fn-redefs [search/reindex! (constantly nil)]
+ (clean-remote-sync-state f)))
+ test-helpers/commit-with-temp)
+
+(defn- rso [entry]
+ (t2/select-one :model/RemoteSyncObject :model_type "Glossary" :model_id (:id entry)))
+
+(defn- with-rso! [entry status]
+ (t2/insert! :model/RemoteSyncObject {:model_type "Glossary"
+ :model_id (:id entry)
+ :model_name (:term entry)
+ :status status
+ :status_changed_at (t/offset-date-time)
+ :content_hash (source/row->content-hash {:model_type "Glossary"
+ :model_id (:id entry)})}))
+
+;;; ------------------------------------------- Event Handler Tests -------------------------------------------
+
+(deftest create-event-tracks-entry-when-library-synced-test
+ (collections.tu/with-library-synced
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary]
+ (let [entry (glossary.core/create-entry! (mt/user->id :rasta) {:term "ARR" :definition "Annual recurring revenue"})]
+ (is (=? {:status "create" :model_name "ARR"} (rso entry))))))))
+
+(deftest create-event-ignored-when-library-not-synced-test
+ (collections.tu/with-library-not-synced
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary]
+ (let [entry (glossary.core/create-entry! (mt/user->id :rasta) {:term "ARR" :definition "Annual recurring revenue"})]
+ (is (nil? (rso entry))))))))
+
+(deftest update-event-marks-synced-entry-for-update-test
+ (collections.tu/with-library-synced
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (with-rso! entry "synced")
+ (testing "saving the same term and definition again stays synced"
+ (glossary.core/update-entry! (mt/user->id :rasta) (:id entry) {:term "ARR" :definition "Annual recurring revenue"})
+ (is (= "synced" (:status (rso entry)))))
+ (testing "an update that changes the content flips to update and refreshes the tracked name"
+ (glossary.core/update-entry! (mt/user->id :rasta) (:id entry) {:term "NRR" :definition "Net revenue retention"})
+ (is (=? {:status "update" :model_name "NRR"} (rso entry))))))))
+
+(deftest delete-event-test
+ (collections.tu/with-library-synced
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (testing "deleting a synced entry marks it for deletion and keeps the tracked name"
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (with-rso! entry "synced")
+ (glossary.core/delete-entry! (mt/user->id :rasta) (:id entry))
+ (is (=? {:status "delete" :model_name "ARR"} (rso entry)))))
+ (testing "deleting a never-pushed entry drops its tracking row"
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (with-rso! entry "create")
+ (glossary.core/delete-entry! (mt/user->id :rasta) (:id entry))
+ (is (nil? (rso entry))))))))
+
+;;; ------------------------------------------- Library Tracking Enable/Disable Tests -------------------------------------------
+
+(deftest enable-library-tracking-marks-every-entry-test
+ (collections.tu/with-library-not-synced
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (rs-events/enable-library-tracking!)
+ (is (=? {:status "create" :model_name "ARR"} (rso entry)))))))
+
+(deftest disable-library-tracking-removes-every-entry-test
+ (collections.tu/with-library-not-synced
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (with-rso! entry "synced")
+ (rs-events/disable-library-tracking!)
+ (is (nil? (rso entry)))))))
+
+(deftest library-sync-status-change-toggles-glossary-tracking-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (collections.tu/with-library [{library :library}]
+ (collections.tu/with-library-not-synced
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (let [publish! (fn []
+ (events/publish-event! :event/collection-update
+ {:object (t2/select-one :model/Collection :id (:id library))
+ :user-id (mt/user->id :rasta)}))]
+ (testing "the Library becoming remote-synced tracks existing entries"
+ (t2/update! :model/Collection (:id library) {:is_remote_synced true})
+ (publish!)
+ (is (=? {:status "create"} (rso entry))))
+ (testing "the Library ceasing to be remote-synced removes their tracking rows"
+ (t2/update! :model/Collection (:id library) {:is_remote_synced false})
+ (publish!)
+ (is (nil? (rso entry))))))))))
+
+;;; ------------------------------------------- Dirty Check Tests -------------------------------------------
+
+(deftest dirty-check-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (with-rso! entry "update")
+ (testing "a pending glossary change counts as dirty when the Library is synced"
+ (collections.tu/with-library-synced
+ (is (sync-object/dirty?))))
+ (testing "and is ignored when the Library is not synced"
+ (collections.tu/with-library-not-synced
+ (is (not (sync-object/dirty?))))))))
+
+;;; ------------------------------------------- Deletion Conflict Tests -------------------------------------------
+
+(deftest unsynced-local-term-absent-from-import-is-a-deletion-conflict-test
+ (collections.tu/with-library-synced
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (let [glossary-conflicts (fn [imported-data]
+ (filter #(= "Glossary" (:model %))
+ (spec/check-content-deletion-conflicts imported-data)))]
+ (testing "a never-synced term the import would delete is reported with its term as the name"
+ (is (=? [{:type :glossary-deletion-conflict :count 1 :names ["ARR"]}]
+ (glossary-conflicts {:by-entity-id {}}))))
+ (testing "a term present in the import is not reported"
+ (is (empty? (glossary-conflicts {:by-entity-id {"Glossary" #{(:entity_id entry)}}}))))
+ (testing "an already-synced term is a normal reconcile, not a conflict"
+ (with-rso! entry "synced")
+ (is (empty? (glossary-conflicts {:by-entity-id {}}))))))))
+
+;;; ------------------------------------------- First-Import Conflict Tests -------------------------------------------
+
+(deftest unsynced-local-glossary-conflicts-with-imported-glossary-test
+ (mt/with-temp [:model/Glossary _ {:term "ARR" :definition "Annual recurring revenue"}]
+ (testing "check-feature-conflicts reports Library content under the snippets conflict type"
+ (let [[conflict :as conflicts] (spec/check-feature-conflicts #{"Glossary"} #{})]
+ (is (= 1 (count conflicts)))
+ (is (=? {:type :snippets-conflict :category "Snippets"} conflict))
+ (is (str/includes? (:message conflict) "Library content (snippets, glossary)"))))
+ (testing "import! surfaces the conflict"
+ (mt/with-model-cleanup [:model/RemoteSyncTask]
+ (let [task-id (t2/insert-returning-pk! :model/RemoteSyncTask {:sync_task_type "import"
+ :initiated_by (mt/user->id :rasta)})
+ test-files {"main" {"collections/main/test_coll/test_coll.yaml"
+ (test-helpers/generate-collection-yaml "test-collection-1xxxx" "Test Collection")
+ "glossary/remote_term.yaml"
+ (test-helpers/generate-glossary-yaml "test-glossary-xxxxxxx" "MRR" "Monthly recurring revenue")}}
+ mock-source (test-helpers/create-mock-source :initial-files test-files)
+ result (impl/import! (source.p/snapshot mock-source) task-id)]
+ (is (= :conflict (:status result)))
+ (is (contains? (:conflicts result) "Snippets"))
+ (is (some #(= :snippets-conflict (:type %)) (:conflict-details result))))))))
+
+;;; ------------------------------------------- Export Tests -------------------------------------------
+
+(defn- repo-files [mock] (get @(:files-atom mock) "main"))
+
+(defn- new-task! [sync-task-type]
+ (t2/insert-returning-pk! :model/RemoteSyncTask {:sync_task_type sync-task-type :initiated_by (mt/user->id :rasta)}))
+
+(defn- written-version [task-id]
+ (t2/select-one-fn :version :model/RemoteSyncTask :id task-id))
+
+(defn- glossary-file-path
+ "The repo path of the file serializing the glossary entry with `entity-id`, or nil."
+ [mock entity-id]
+ (some (fn [[path content]]
+ (when (and (str/starts-with? path "glossary/")
+ (= entity-id (:entity_id (yaml/parse-string content))))
+ path))
+ (repo-files mock)))
+
+(defn- run-export!
+ "Exports to `mock` under a fresh task and returns `[task-id result]`. Earlier tasks are dropped first: the mock
+ source reports a constant version, so a completed task left as the sync base would read as remote divergence."
+ [mock message]
+ (t2/delete! :model/RemoteSyncTask)
+ (let [task (new-task! "export")]
+ [task (impl/export! (source.p/snapshot mock) task message)]))
+
+(defn- run-import!
+ "Imports `snapshot` under a new task, completes the task, and returns the result."
+ [snapshot & opts]
+ (let [task (new-task! "import")
+ result (apply impl/import! snapshot task opts)]
+ (impl/handle-task-result! result task)
+ result))
+
+(defn- export-entry!
+ "Marks `entry` as new, exports it to a fresh empty source and returns the mock source."
+ [entry]
+ (with-rso! entry "create")
+ (let [mock (test-helpers/create-mock-source :initial-files {"main" {}})
+ [_ result] (run-export! mock "initial")]
+ (is (= :success (:status result)) (str "initial export should succeed: " result))
+ mock))
+
+(deftest export-writes-glossary-file-and-marks-entry-synced-test
+ (collections.tu/with-library-synced
+ (mt/with-temporary-setting-values [remote-sync-type :read-write remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/RemoteSyncTask]
+ (mt/with-temp [:model/Glossary {eid :entity_id :as entry} {:term "ARR" :definition "Annual recurring revenue"}]
+ (let [mock (export-entry! entry)
+ path (glossary-file-path mock eid)]
+ (testing "the entry is written under glossary/ at a path derived from the term"
+ (is (= "glossary/arr.yaml" path)))
+ (testing "the ledger row is synced and records the file path and content hash"
+ (is (=? {:status "synced" :file_path path :content_hash string?} (rso entry))))))))))
+
+(deftest export-removes-stale-glossary-files-when-library-not-synced-test
+ (collections.tu/with-library-not-synced
+ (mt/with-temporary-setting-values [remote-sync-type :read-write remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/RemoteSyncTask]
+ ;; No dirty rows: the export reaches the incremental path with an empty plan and only the stale deletes.
+ (let [stale-path "glossary/arr.yaml"
+ mock (test-helpers/create-mock-source
+ :initial-files {"main" {stale-path (test-helpers/generate-glossary-yaml
+ "stale-glossary-xxxxxxx" "ARR" "Annual recurring revenue")}})
+ [_ result] (run-export! mock "remove stale glossary")]
+ (is (= :success (:status result)))
+ (is (nil? (get (repo-files mock) stale-path))
+ "a glossary file left behind after the Library was un-synced is deleted on export"))))))
+
+(deftest term-rename-uses-incremental-export-path-test
+ (collections.tu/with-library-synced
+ (mt/with-temporary-setting-values [remote-sync-type :read-write remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/RemoteSyncTask]
+ (mt/with-temp [:model/Glossary {eid :entity_id :as entry} {:term "ARR" :definition "Annual recurring revenue"}]
+ (let [mock (export-entry! entry)
+ old-path (glossary-file-path mock eid)]
+ (glossary.core/update-entry! (mt/user->id :rasta) (:id entry)
+ {:term "Annual Recurring Revenue" :definition (:definition entry)})
+ (is (= "update" (:status (rso entry))))
+ (let [[task result] (run-export! mock "rename")
+ new-path (glossary-file-path mock eid)]
+ (is (= :success (:status result)))
+ (is (= "apply-changes-version" (written-version task)) "the rename is exported incrementally")
+ (is (= "glossary/annual_recurring_revenue.yaml" new-path))
+ (is (not (contains? (repo-files mock) old-path)) "the file at the old term's path is deleted")
+ (is (=? {:status "synced" :file_path new-path} (rso entry))))))))))
+
+;;; ------------------------------------------- Import Tests -------------------------------------------
+
+(def ^:private library-yaml-path "collections/library/library.yaml")
+
+(defn- library-yaml
+ "The Library collection as a read-write instance exports it, so an import keeps the Library synced."
+ []
+ (test-helpers/generate-collection-yaml collection/library-entity-id "Library" :type "library" :is-remote-synced true))
+
+(defn- do-with-synced-library!
+ "Runs `f` with a remote-synced Library collection carrying the canonical Library entity_id, so it matches
+ the Library in an imported snapshot."
+ [f]
+ (t2/delete! :model/Collection :entity_id collection/library-entity-id)
+ (mt/with-temp [:model/Collection _ {:name "Library"
+ :type "library"
+ :entity_id collection/library-entity-id
+ :is_remote_synced true
+ :location "/"}]
+ (f)))
+
+(def ^:private test-collection-path "collections/main/test_coll/test_coll.yaml")
+
+(deftest import-creates-glossary-entries-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary :model/Collection :model/RemoteSyncTask]
+ (do-with-synced-library!
+ (fn []
+ (let [eid "test-glossary-xxxxxxx"
+ path "glossary/mrr.yaml"
+ files {"main" {library-yaml-path (library-yaml)
+ test-collection-path (test-helpers/generate-collection-yaml "test-collection-1xxxx" "Test Collection")
+ path (test-helpers/generate-glossary-yaml eid "MRR" "Monthly recurring revenue")}}
+ mock (test-helpers/create-mock-source :initial-files files)
+ result (run-import! (source.p/snapshot mock) :force? true)]
+ (is (= :success (:status result)) (str "import should succeed: " result))
+ (let [entry (t2/select-one :model/Glossary :entity_id eid)]
+ (is (=? {:term "MRR" :definition "Monthly recurring revenue"} entry))
+ (testing "the ledger is rebuilt with a synced row carrying the file path and content hash"
+ (is (=? {:status "synced" :model_name "MRR" :file_path path :content_hash string?} (rso entry)))))))))))
+
+(deftest import-removes-synced-terms-absent-from-snapshot-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Collection :model/RemoteSyncTask]
+ (do-with-synced-library!
+ (fn []
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (let [files {"main" {library-yaml-path (library-yaml)
+ test-collection-path (test-helpers/generate-collection-yaml "test-collection-1xxxx" "Test Collection")}}
+ mock (test-helpers/create-mock-source :initial-files files)]
+ (testing "a never-pushed local term the import would delete blocks the import"
+ (with-rso! entry "create")
+ (let [result (run-import! (source.p/snapshot mock) :force? true :force-deletion? false)]
+ (is (= :conflict (:status result)))
+ (is (some #(= :glossary-deletion-conflict (:type %)) (:conflict-details result)))
+ (is (t2/exists? :model/Glossary :id (:id entry)))))
+ (testing "an already-synced local term absent from the import is deleted"
+ (t2/update! :model/RemoteSyncObject :model_type "Glossary" :model_id (:id entry) {:status "synced"})
+ (let [result (run-import! (source.p/snapshot mock) :force? true :force-deletion? false)]
+ (is (= :success (:status result)) (str "import should succeed: " result))
+ (is (not (t2/exists? :model/Glossary :id (:id entry))))
+ (is (nil? (rso entry))))))))))))
+
+(deftest term-keyed-file-survives-full-import-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary :model/Collection :model/RemoteSyncTask]
+ (do-with-synced-library!
+ (fn []
+ (let [legacy (fn [term definition]
+ {"main" {library-yaml-path (library-yaml)
+ test-collection-path (test-helpers/generate-collection-yaml "test-collection-1xxxx" "Test Collection")
+ (str "glossary/" (u/lower-case-en term) ".yaml")
+ (test-helpers/generate-legacy-glossary-yaml term definition)}})]
+ (testing "a term-keyed file updates the matching local row and the full import keeps it"
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "local"}]
+ (with-rso! entry "synced")
+ (let [mock (test-helpers/create-mock-source :initial-files (legacy "ARR" "from the repo"))
+ result (run-import! (source.p/snapshot mock) :force? true)]
+ (is (= :success (:status result)) (str "import should succeed: " result))
+ (is (=? {:id (:id entry) :entity_id (:entity_id entry) :definition "from the repo"}
+ (t2/select-one :model/Glossary :term "ARR")))
+ (is (=? {:status "synced"} (rso entry))))))
+ (testing "a term-keyed file with no local match is inserted and kept across full imports"
+ (let [mock (test-helpers/create-mock-source :initial-files (legacy "Bookings" "Signed contracts"))]
+ (is (= :success (:status (run-import! (source.p/snapshot mock) :force? true))))
+ (let [{:keys [id entity_id]} (t2/select-one :model/Glossary :term "Bookings")]
+ (is (= 21 (count entity_id)))
+ (is (= :success (:status (run-import! (source.p/snapshot mock) :force? true))))
+ (is (= [id] (t2/select-fn-vec :id :model/Glossary :term "Bookings"))))))
+ (testing "an unsynced local row matched by term is not reported as a deletion"
+ (mt/with-temp [:model/Glossary entry {:term "MRR" :definition "local"}]
+ (with-rso! entry "create")
+ (let [mock (test-helpers/create-mock-source :initial-files (legacy "MRR" "from the repo"))
+ result (run-import! (source.p/snapshot mock) :force? true :force-deletion? false)]
+ (is (= :success (:status result)) (str "import should succeed: " result))
+ (is (= "from the repo" (t2/select-one-fn :definition :model/Glossary :id (:id entry)))))))))))))
+
+(deftest extract-imported-entities-resolves-term-keyed-paths-test
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}
+ :model/Glossary shaped {:term "CustomerLifetimeValue" :definition "21 nano-id characters"}]
+ (let [resolve (fn [id]
+ (get-in (spec/extract-imported-entities [[{:model "Glossary" :id id}]])
+ [:by-entity-id "Glossary"]))]
+ (testing "an entity_id path is passed through"
+ (is (= #{(:entity_id entry)} (resolve (:entity_id entry)))))
+ (testing "a term-keyed path resolves to the matching row's entity_id"
+ (is (= #{(:entity_id entry)} (resolve "ARR"))))
+ (testing "a term that is itself 21 nano-id characters still resolves by term"
+ (is (= #{(:entity_id shaped)} (resolve "CustomerLifetimeValue"))))
+ (testing "a path matching no local row keeps its raw id"
+ (is (= #{"No such term"} (resolve "No such term"))))
+ (testing "with ingest-one, an entity_id path matching no row resolves to the row matching the entity's term"
+ (is (= #{(:entity_id entry)}
+ (get-in (spec/extract-imported-entities [[{:model "Glossary" :id "glossaryfileeidAAAA01"}]]
+ (constantly {:term "ARR" :definition "from the repo"}))
+ [:by-entity-id "Glossary"]))))
+ (testing "with ingest-one, an entity_id path matching neither a row nor a term keeps its raw id"
+ (is (= #{"glossaryfileeidAAAA02"}
+ (get-in (spec/extract-imported-entities [[{:model "Glossary" :id "glossaryfileeidAAAA02"}]]
+ (constantly {:term "No such term" :definition "x"}))
+ [:by-entity-id "Glossary"])))))))
+
+(def ^:private base-tree
+ "A snapshot with the synced Library and one plain collection, and no glossary files."
+ {library-yaml-path (library-yaml)
+ test-collection-path (test-helpers/generate-collection-yaml "test-collection-1xxxx" "Test Collection")})
+
+(defn- import-v0-then-v1!
+ "Force-imports tree `v0`, then imports `v1` as a normal pull. Returns true when the second import took the
+ incremental fast path."
+ [v0 v1]
+ (let [src (test-helpers/versioned-source :trees {"v0" v0 "v1" v1} :current "v0")
+ incremental? (atom false)]
+ (is (= :success (:status (run-import! (source.p/snapshot-at src "v0") :force? true))))
+ (mt/with-dynamic-fn-redefs [impl/incremental-load-snapshot!
+ (fn [& args]
+ (reset! incremental? true)
+ (apply (mt/original-fn #'impl/incremental-load-snapshot!) args))]
+ (is (= :success (:status (run-import! (source.p/snapshot-at src "v1"))))))
+ @incremental?))
+
+(deftest changed-glossary-file-imports-incrementally-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary :model/Collection :model/RemoteSyncTask]
+ (do-with-synced-library!
+ (fn []
+ (let [eid "test-glossary-xxxxxxx"
+ path "glossary/mrr.yaml"
+ v0 (assoc base-tree path (test-helpers/generate-glossary-yaml eid "MRR" "Monthly recurring revenue"))
+ v1 (assoc base-tree path (test-helpers/generate-glossary-yaml eid "MRR" "Monthly recurring revenue, net of churn"))]
+ (is (true? (import-v0-then-v1! v0 v1)) "a changed glossary file takes the incremental import fast path")
+ (let [entry (t2/select-one :model/Glossary :entity_id eid)]
+ (is (= "Monthly recurring revenue, net of churn" (:definition entry)))
+ (is (=? {:status "synced" :file_path path} (rso entry))))))))))
+
+(deftest added-glossary-file-imports-incrementally-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary :model/Collection :model/RemoteSyncTask]
+ (do-with-synced-library!
+ (fn []
+ (let [eid "test-glossary-xxxxxxx"
+ path "glossary/mrr.yaml"
+ v1 (assoc base-tree path (test-helpers/generate-glossary-yaml eid "MRR" "Monthly recurring revenue"))]
+ (is (true? (import-v0-then-v1! base-tree v1)) "a new glossary file takes the incremental import fast path")
+ (let [entry (t2/select-one :model/Glossary :entity_id eid)]
+ (is (=? {:term "MRR" :definition "Monthly recurring revenue"} entry))
+ (is (=? {:status "synced" :model_name "MRR" :file_path path :content_hash string?} (rso entry))))))))))
+
+(deftest deleted-glossary-file-imports-incrementally-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary :model/Collection :model/RemoteSyncTask]
+ (do-with-synced-library!
+ (fn []
+ (let [eid "test-glossary-xxxxxxx"
+ path "glossary/mrr.yaml"
+ v0 (assoc base-tree path (test-helpers/generate-glossary-yaml eid "MRR" "Monthly recurring revenue"))]
+ (is (true? (import-v0-then-v1! v0 base-tree)) "a deleted glossary file takes the incremental import fast path")
+ (is (nil? (t2/select-one :model/Glossary :entity_id eid)) "the entry is deleted")
+ (is (nil? (t2/select-one :model/RemoteSyncObject :model_type "Glossary" :file_path path)) "its ledger row is removed")))))))
+
+(deftest nano-id-shaped-term-keyed-file-survives-import-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary :model/Collection :model/RemoteSyncTask]
+ (do-with-synced-library!
+ (fn []
+ (let [term "CustomerLifetimeValue"
+ path (str "glossary/" (u/lower-case-en term) ".yaml")
+ files (assoc base-tree path (test-helpers/generate-legacy-glossary-yaml term "from the repo"))]
+ (testing "a synced local row matched by a 21-character term survives a full import"
+ (mt/with-temp [:model/Glossary entry {:term term :definition "local"}]
+ (with-rso! entry "synced")
+ (let [mock (test-helpers/create-mock-source :initial-files {"main" files})]
+ (is (= :success (:status (run-import! (source.p/snapshot mock) :force? true))))
+ (is (=? {:id (:id entry) :entity_id (:entity_id entry) :definition "from the repo"}
+ (t2/select-one :model/Glossary :term term)))
+ (is (=? {:status "synced" :file_path path} (rso entry))))))
+ (testing "with no local row the term lands on a full import and gets a ledger row"
+ (let [mock (test-helpers/create-mock-source :initial-files {"main" files})]
+ (is (= :success (:status (run-import! (source.p/snapshot mock) :force? true :force-deletion? false))))
+ (is (=? {:status "synced" :file_path path} (rso (t2/select-one :model/Glossary :term term))))))
+ (testing "the term lands with a ledger row on an incremental import"
+ (t2/delete! :model/Glossary :term term)
+ (is (true? (import-v0-then-v1! base-tree files)))
+ (is (=? {:status "synced" :file_path path} (rso (t2/select-one :model/Glossary :term term)))))))))))
+
+(deftest entity-id-keyed-file-matching-local-term-is-not-a-deletion-conflict-test
+ (mt/with-temporary-setting-values [remote-sync-enabled true]
+ (mt/with-model-cleanup [:model/Glossary :model/Collection :model/RemoteSyncTask]
+ (do-with-synced-library!
+ (fn []
+ (let [file-eid "glossaryfileeidAAAA01"
+ path "glossary/arr.yaml"
+ files (assoc base-tree path (test-helpers/generate-glossary-yaml file-eid "ARR" "from the repo"))
+ mock (test-helpers/create-mock-source :initial-files {"main" files})]
+ (testing "an unsynced local row holding the file's term under another entity_id is updated in place"
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "local"}]
+ (with-rso! entry "create")
+ (let [result (run-import! (source.p/snapshot mock) :force? true :force-deletion? false)]
+ (is (= :success (:status result)) (str "import should succeed: " result))
+ (is (= [(:id entry)] (t2/select-fn-vec :id :model/Glossary :term "ARR")))
+ (is (=? {:entity_id file-eid :definition "from the repo"} (t2/select-one :model/Glossary :id (:id entry))))
+ (is (=? {:status "synced" :file_path path} (rso entry))))))))))))
diff --git a/enterprise/backend/test/metabase_enterprise/remote_sync/impl_test.clj b/enterprise/backend/test/metabase_enterprise/remote_sync/impl_test.clj
index 210d65e980a..5d9f76930cd 100644
--- a/enterprise/backend/test/metabase_enterprise/remote_sync/impl_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/remote_sync/impl_test.clj
@@ -264,6 +264,21 @@
(is (= {:kind "pulled" :count 3 :branch "main"} (:outcome task)))
(is (= :successful (:status (t2/hydrate task :status)))))))))
+(deftest handle-task-result!-stores-conflict-categories-test
+ (testing "handle-task-result! records a conflict result's category set on the task as a vector"
+ (mt/with-model-cleanup [:model/RemoteSyncTask]
+ (let [task-id (t2/insert-returning-pk! :model/RemoteSyncTask
+ {:sync_task_type "import"
+ :initiated_by (mt/user->id :rasta)})]
+ (impl/handle-task-result! {:status :conflict
+ :version "abc123"
+ :conflicts #{"Snippets"}}
+ task-id)
+ (let [task (t2/select-one :model/RemoteSyncTask :id task-id)]
+ (is (some? (:ended_at task)))
+ (is (= "abc123" (:version task)))
+ (is (= ["Snippets"] (:conflicts task))))))))
+
(deftest import!-proceeds-when-version-matches-with-force-test
(testing "import! proceeds with import when source version matches last imported version but force? is true"
(mt/with-model-cleanup [:model/Collection :model/RemoteSyncTask]
diff --git a/enterprise/backend/test/metabase_enterprise/remote_sync/init_test.clj b/enterprise/backend/test/metabase_enterprise/remote_sync/init_test.clj
index c87e15a500e..e36e2699f02 100644
--- a/enterprise/backend/test/metabase_enterprise/remote_sync/init_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/remote_sync/init_test.clj
@@ -1,11 +1,15 @@
(ns metabase-enterprise.remote-sync.init-test
(:require
[clojure.test :refer :all]
+ [java-time.api :as t]
+ [metabase-enterprise.remote-sync.events :as rs-events]
[metabase-enterprise.remote-sync.impl :as impl]
[metabase-enterprise.remote-sync.init :as init]
[metabase-enterprise.remote-sync.models.remote-sync-object :as remote-sync.object]
[metabase.collections.models.collection :as collection]
- [metabase.test :as mt]))
+ [metabase.collections.test-utils :as collections.tu]
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
(defn- capture-async-import! []
(let [calls (atom [])]
@@ -100,3 +104,79 @@
(mt/with-temp [:model/Collection _ {:name "Synced" :is_remote_synced true}]
(#'init/remote-sync-init)
(is (empty? @calls))))))))
+
+;;; ------------------------------------------- Glossary ledger backfill -------------------------------------------
+
+(defn- glossary-rso-count []
+ (t2/count :model/RemoteSyncObject :model_type "Glossary"))
+
+(defn- do-with-untracked-glossary-entry!
+ "Runs `f` with one glossary entry and no Glossary ledger rows, under `remote-sync-type` `sync-type`."
+ [sync-type f]
+ (mt/with-temporary-setting-values [:remote-sync-url "file://my/repo.git"
+ :remote-sync-type sync-type
+ :remote-sync-branch "main"]
+ (mt/with-model-cleanup [:model/RemoteSyncObject]
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (t2/delete! :model/RemoteSyncObject :model_type "Glossary")
+ (mt/with-dynamic-fn-redefs [impl/async-import! (constantly nil)
+ remote-sync.object/dirty? (constantly false)]
+ (f entry))))))
+
+(deftest remote-sync-init-backfills-glossary-tracking-test
+ (testing "Read-write with a synced Library tracks every untracked glossary entry as 'create', once"
+ (collections.tu/with-library-synced
+ (do-with-untracked-glossary-entry!
+ :read-write
+ (fn [entry]
+ (#'init/remote-sync-init)
+ (is (=? {:status "create" :model_name "ARR"}
+ (t2/select-one :model/RemoteSyncObject :model_type "Glossary" :model_id (:id entry))))
+ (is (= 1 (glossary-rso-count)))
+ (testing "a second run inserts nothing"
+ (#'init/remote-sync-init)
+ (is (= 1 (glossary-rso-count)))))))))
+
+(deftest remote-sync-init-glossary-backfill-tracks-only-untracked-entries-test
+ (testing "A partially tracked glossary gets ledger rows for the untracked entries only; tracked rows are left alone"
+ (collections.tu/with-library-synced
+ (do-with-untracked-glossary-entry!
+ :read-write
+ (fn [entry]
+ (mt/with-temp [:model/Glossary tracked {:term "MRR" :definition "Monthly recurring revenue"}]
+ (t2/insert! :model/RemoteSyncObject {:model_type "Glossary" :model_id (:id tracked) :model_name "MRR"
+ :status "synced" :status_changed_at (t/offset-date-time)})
+ (#'init/remote-sync-init)
+ (is (= 2 (glossary-rso-count)))
+ (is (=? {:status "create" :model_name "ARR"}
+ (t2/select-one :model/RemoteSyncObject :model_type "Glossary" :model_id (:id entry))))
+ (is (=? {:status "synced" :model_name "MRR"}
+ (t2/select-one :model/RemoteSyncObject :model_type "Glossary" :model_id (:id tracked))))))))))
+
+(deftest backfill-glossary-tracking-returns-inserted-count-test
+ (testing "the backfill returns how many ledger rows it inserted, and zero once every entry is tracked"
+ (collections.tu/with-library-synced
+ (do-with-untracked-glossary-entry!
+ :read-write
+ (fn [_entry]
+ (is (= 1 (rs-events/backfill-glossary-tracking!)))
+ (is (= 0 (rs-events/backfill-glossary-tracking!)))
+ (is (= 1 (glossary-rso-count))))))))
+
+(deftest remote-sync-init-glossary-backfill-skips-read-only-test
+ (testing "A read-only instance is not backfilled"
+ (collections.tu/with-library-synced
+ (do-with-untracked-glossary-entry!
+ :read-only
+ (fn [_entry]
+ (#'init/remote-sync-init)
+ (is (zero? (glossary-rso-count))))))))
+
+(deftest remote-sync-init-glossary-backfill-skips-unsynced-library-test
+ (testing "Glossary entries are only tracked when the Library is synced"
+ (collections.tu/with-library-not-synced
+ (do-with-untracked-glossary-entry!
+ :read-write
+ (fn [_entry]
+ (#'init/remote-sync-init)
+ (is (zero? (glossary-rso-count))))))))
diff --git a/enterprise/backend/test/metabase_enterprise/remote_sync/merge_test.clj b/enterprise/backend/test/metabase_enterprise/remote_sync/merge_test.clj
index 464eea15167..a25602a45eb 100644
--- a/enterprise/backend/test/metabase_enterprise/remote_sync/merge_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/remote_sync/merge_test.clj
@@ -11,6 +11,15 @@
{:path (str "collections/" name ".yaml")
:content (str "serdes/meta:\n- model: Card\n id: " id "\n label: " name "\nname: " name "\n" extra)}))
+(defn- glossary-entry
+ "Builds a `{:path :content}` spec for a Glossary entry with entity `id`, `term` (the file name, as the export
+ slugs it) and an optional `definition` to vary the body."
+ ([id term] (glossary-entry id term "def"))
+ ([id term definition]
+ {:path (str "glossary/" term ".yaml")
+ :content (str "serdes/meta:\n- model: Glossary\n id: " id "\n label: " term "\nentity_id: " id
+ "\nterm: " term "\ndefinition: " definition "\n")}))
+
(defn- ids
"Sorted entity ids present in a merge result's :merged set."
[result]
@@ -38,6 +47,25 @@
(is (= 1 (count (:conflicts result))))
(is (empty? (:merged result))))))
+(deftest ^:parallel glossary-disjoint-edits-merge-clean-test
+ (testing "local edits term A's definition and remote edits term B's -> both merged, no conflict"
+ (let [base [(glossary-entry "A" "arr") (glossary-entry "B" "mrr")]
+ ours [(glossary-entry "A" "arr" "ours") (glossary-entry "B" "mrr")]
+ theirs [(glossary-entry "A" "arr") (glossary-entry "B" "mrr" "theirs")]
+ result (remote-sync.merge/three-way-merge base ours theirs)]
+ (is (empty? (:conflicts result)))
+ (is (= ["A" "B"] (ids result)))
+ (is (= {:added 0 :updated 1 :removed 0} (:summary result))))))
+
+(deftest ^:parallel glossary-same-term-edited-both-sides-is-conflict-test
+ (testing "the same term's definition edited differently on both sides -> conflict"
+ (let [result (remote-sync.merge/three-way-merge
+ [(glossary-entry "A" "arr")]
+ [(glossary-entry "A" "arr" "ours")]
+ [(glossary-entry "A" "arr" "theirs")])]
+ (is (= 1 (count (:conflicts result))))
+ (is (empty? (:merged result))))))
+
(deftest ^:parallel local-edit-vs-remote-rename-is-conflict-test
(testing "local edits A's content while remote renames A -> conflict (both changed the same entity)"
(let [result (remote-sync.merge/three-way-merge
diff --git a/enterprise/backend/test/metabase_enterprise/remote_sync/permissions_test.clj b/enterprise/backend/test/metabase_enterprise/remote_sync/permissions_test.clj
index 26477e61f08..8bcd4edc239 100644
--- a/enterprise/backend/test/metabase_enterprise/remote_sync/permissions_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/remote_sync/permissions_test.clj
@@ -4,6 +4,7 @@
[clojure.test :refer :all]
[metabase-enterprise.remote-sync.settings :as settings]
[metabase.collections.models.collection :as collections]
+ [metabase.collections.test-utils :as collections.tu]
[metabase.lib.core :as lib]
[metabase.models.interface :as mi]
[metabase.test :as mt]
@@ -755,3 +756,48 @@
:schema "public"
:name "target_table"}}))
"Non-superuser should not be able to create transforms even when remote-sync-type is read-write")))))))
+
+;;; ------------------------------------------- Glossary -------------------------------------------
+
+(deftest glossary-write-endpoints-return-403-in-read-only-remote-sync-test
+ (testing "POST/PUT/DELETE /api/glossary reject with 403 when remote sync is read-only and the Library is synced"
+ (mt/with-temporary-setting-values [settings/remote-sync-url "https://github.com/test/repo.git"
+ settings/remote-sync-type :read-only]
+ (collections.tu/with-library-synced
+ (mt/with-model-cleanup [:model/Glossary :model/RemoteSyncObject]
+ (mt/with-temp [:model/Glossary {id :id} {:term "ARR" :definition "Annual recurring revenue"}]
+ (testing "POST is rejected"
+ (is (= "You don't have permissions to do that."
+ (mt/user-http-request :crowberto :post 403 "glossary" {:term "MRR" :definition "Monthly recurring revenue"}))))
+ (testing "PUT is rejected"
+ (is (= "You don't have permissions to do that."
+ (mt/user-http-request :crowberto :put 403 (str "glossary/" id) {:term "ARR" :definition "changed"}))))
+ (testing "DELETE is rejected"
+ (is (= "You don't have permissions to do that."
+ (mt/user-http-request :crowberto :delete 403 (str "glossary/" id)))))
+ (testing "the entry is untouched"
+ (is (= "Annual recurring revenue" (t2/select-one-fn :definition :model/Glossary :id id))))
+ (testing "GET still works and reports the glossary as not writable"
+ (let [response (mt/user-http-request :crowberto :get 200 "glossary")]
+ (is (some #(= id (:id %)) (:data response)))
+ (is (false? (:can_write response)))))))))))
+
+(deftest glossary-write-endpoints-allowed-when-editable-test
+ (mt/with-model-cleanup [:model/Glossary :model/RemoteSyncObject]
+ (mt/with-temp [:model/Glossary {id :id} {:term "ARR" :definition "Annual recurring revenue"}]
+ (testing "PUT /api/glossary/:id succeeds in read-write mode with the Library synced"
+ (mt/with-temporary-setting-values [settings/remote-sync-url "https://github.com/test/repo.git"
+ settings/remote-sync-type :read-write]
+ (collections.tu/with-library-synced
+ (is (true? (:can_write (mt/user-http-request :crowberto :get 200 "glossary"))))
+ (is (= "read-write edit"
+ (:definition (mt/user-http-request :crowberto :put 200 (str "glossary/" id)
+ {:term "ARR" :definition "read-write edit"})))))))
+ (testing "PUT /api/glossary/:id succeeds in read-only mode when the Library is not synced"
+ (mt/with-temporary-setting-values [settings/remote-sync-url "https://github.com/test/repo.git"
+ settings/remote-sync-type :read-only]
+ (collections.tu/with-library-not-synced
+ (is (true? (:can_write (mt/user-http-request :crowberto :get 200 "glossary"))))
+ (is (= "unsynced edit"
+ (:definition (mt/user-http-request :crowberto :put 200 (str "glossary/" id)
+ {:term "ARR" :definition "unsynced edit"}))))))))))
diff --git a/enterprise/backend/test/metabase_enterprise/remote_sync/snippets_test.clj b/enterprise/backend/test/metabase_enterprise/remote_sync/snippets_test.clj
index b6ddf32ca84..b4eb487856b 100644
--- a/enterprise/backend/test/metabase_enterprise/remote_sync/snippets_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/remote_sync/snippets_test.clj
@@ -140,7 +140,7 @@
:model/NativeQuerySnippet snippet {:name "Existing Snippet" :content "SELECT 1" :collection_id coll-id}]
(is (zero? (t2/count :model/RemoteSyncObject :model_type "NativeQuerySnippet"))
"Should have no snippet tracking entries initially")
- (rs-events/enable-snippet-tracking!)
+ (rs-events/enable-library-tracking!)
;; Verify tracking entries created
(is (t2/exists? :model/RemoteSyncObject
:model_type "Collection"
@@ -173,7 +173,7 @@
(is (= 2 (t2/count :model/RemoteSyncObject :model_type [:in ["Collection" "NativeQuerySnippet"]]
:model_id [:in [coll-id (:id snippet)]]))
"Should have 2 tracking entries")
- (rs-events/disable-snippet-tracking!)
+ (rs-events/disable-library-tracking!)
;; Verify tracking entries removed
(is (zero? (t2/count :model/RemoteSyncObject :model_type "NativeQuerySnippet"))
"Snippet tracking entries should be removed")
diff --git a/enterprise/backend/test/metabase_enterprise/remote_sync/spec_test.clj b/enterprise/backend/test/metabase_enterprise/remote_sync/spec_test.clj
index 36774016676..fbc71bb231e 100644
--- a/enterprise/backend/test/metabase_enterprise/remote_sync/spec_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/remote_sync/spec_test.clj
@@ -6,6 +6,7 @@
[metabase-enterprise.remote-sync.db :as remote-sync.db]
[metabase-enterprise.remote-sync.spec :as spec]
[metabase-enterprise.transforms-python.core :as transforms-python]
+ [metabase.collections.test-utils :as collections.tu]
[metabase.test :as mt]
[toucan2.core :as t2]))
@@ -130,7 +131,8 @@
(is (contains? types "Measure"))
(is (contains? types "Transform"))
(is (contains? types "TransformTag"))
- (is (= 13 (count types))))))
+ (is (contains? types "Glossary"))
+ (is (= 14 (count types))))))
(deftest specs-by-identity-type-test
(testing "specs-by-identity-type filters correctly"
@@ -164,10 +166,16 @@
(testing "excluded-model-types when transforms enabled"
(mt/with-temporary-setting-values [remote-sync-transforms true]
(let [excluded (spec/excluded-model-types)]
- ;; NativeQuerySnippet is still excluded because Library isn't remote-synced
+ ;; Library content is still excluded because Library isn't remote-synced
(is (not (contains? excluded "Transform")))
(is (not (contains? excluded "TransformTag")))
- (is (contains? excluded "NativeQuerySnippet"))))))
+ (is (contains? excluded "NativeQuerySnippet"))
+ (is (contains? excluded "Glossary")))))
+ (testing "excluded-model-types when Library is remote-synced"
+ (collections.tu/with-library-synced
+ (let [excluded (spec/excluded-model-types)]
+ (is (not (contains? excluded "NativeQuerySnippet")))
+ (is (not (contains? excluded "Glossary")))))))
(deftest spec-enabled?-test
(testing "spec-enabled? with always-enabled spec"
@@ -190,7 +198,16 @@
(let [enabled (spec/enabled-specs)]
(is (contains? enabled :model/Card))
(is (contains? enabled :model/Transform))
- (is (contains? enabled :model/TransformTag))))))
+ (is (contains? enabled :model/TransformTag)))))
+ (testing "enabled-specs includes Library content only when the Library is remote-synced"
+ (collections.tu/with-library-not-synced
+ (let [enabled (spec/enabled-specs)]
+ (is (not (contains? enabled :model/NativeQuerySnippet)))
+ (is (not (contains? enabled :model/Glossary)))))
+ (collections.tu/with-library-synced
+ (let [enabled (spec/enabled-specs)]
+ (is (contains? enabled :model/NativeQuerySnippet))
+ (is (contains? enabled :model/Glossary))))))
;;; ------------------------------------------------ Event Helper Tests ------------------------------------------------
diff --git a/enterprise/backend/test/metabase_enterprise/remote_sync/test_helpers.clj b/enterprise/backend/test/metabase_enterprise/remote_sync/test_helpers.clj
index 170f96d33ce..2b49d5e3fc4 100644
--- a/enterprise/backend/test/metabase_enterprise/remote_sync/test_helpers.clj
+++ b/enterprise/backend/test/metabase_enterprise/remote_sync/test_helpers.clj
@@ -13,16 +13,17 @@
(defn generate-collection-yaml
"Generate YAML content for a collection with the given `entity-id` and `name`.
- Optionally accepts `:parent-id` for nested collections and `:namespace` for
- namespace collections (e.g., \"transforms\" or \"snippets\")."
- [entity-id name & {:keys [parent-id namespace]}]
- (format "name: %s
+ Optionally accepts `:parent-id` for nested collections, `:namespace` for namespace collections (e.g.,
+ \"transforms\" or \"snippets\"), `:type` (e.g., \"library\"), and `:is-remote-synced` (emitted only when given)."
+ [entity-id name & {:keys [parent-id namespace type is-remote-synced]}]
+ (str
+ (format "name: %s
description: null
entity_id: %s
slug: %s
created_at: '2024-08-28T09:46:18.671622Z'
archived: false
-type: null
+type: %s
parent_id: %s
personal_owner_id: null
namespace: %s
@@ -35,8 +36,10 @@ archive_operation_id: null
archived_directly: null
is_sample: false
"
- name entity-id (str/replace (u/lower-case-en name) #"\s+" "_")
- (or parent-id "null") (or namespace "null") entity-id (str/replace (u/lower-case-en name) #"\s+" "_")))
+ name entity-id (str/replace (u/lower-case-en name) #"\s+" "_") (or type "null")
+ (or parent-id "null") (or namespace "null") entity-id (str/replace (u/lower-case-en name) #"\s+" "_"))
+ (when (some? is-remote-synced)
+ (format "is_remote_synced: %s\n" is-remote-synced))))
(defn generate-v57-collection-yaml
"Generate YAML content for a collection in v57 format. In v57, remote-synced collections
@@ -783,6 +786,34 @@ serdes/meta:
name entity-id content (or collection-id "null")
entity-id (str/replace (u/lower-case-en name) #"\s+" "_")))
+(defn generate-glossary-yaml
+ "Generates YAML content for a Glossary entry."
+ [entity-id term definition]
+ (format "entity_id: %s
+term: %s
+definition: %s
+created_at: '2024-08-28T09:46:18.671622Z'
+creator_id: [email protected]
+serdes/meta:
+- id: %s
+ label: %s
+ model: Glossary
+"
+ entity-id term definition entity-id (str/replace (u/lower-case-en term) #"\s+" "_")))
+
+(defn generate-legacy-glossary-yaml
+ "Generates YAML content for a Glossary entry as exported before `entity_id` existed: keyed on the term."
+ [term definition]
+ (format "term: %s
+definition: %s
+created_at: '2024-08-28T09:46:18.671622Z'
+creator_id: [email protected]
+serdes/meta:
+- id: %s
+ model: Glossary
+"
+ term definition term))
+
(defn generate-transform-tag-yaml
"Generates YAML content for a TransformTag with the given `entity-id` and `name`."
[entity-id name]
diff --git a/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj b/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj
index b72c17c817b..bd943a50660 100644
--- a/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj
@@ -29,9 +29,7 @@
;; serdes path nests under that entity, so it has no generated entity_id.
:model/OsiAiContext
;; Settings have human-selected unique names.
- :model/Setting
- ;; Glossary items have unique `term` key
- :model/Glossary})
+ :model/Setting})
(def ^:private entities-not-exported
"Entities that are either:
diff --git a/enterprise/backend/test/metabase_enterprise/serialization/v2/extract_test.clj b/enterprise/backend/test/metabase_enterprise/serialization/v2/extract_test.clj
index b8530b6c9e4..d8c6acdd4b2 100644
--- a/enterprise/backend/test/metabase_enterprise/serialization/v2/extract_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/serialization/v2/extract_test.clj
@@ -2170,12 +2170,14 @@
(is (= expected result))))))))
(deftest glossary-test
- (testing "Glossary entries are extracted well"
- (mt/with-temp [:model/Glossary _ {:term "foobar"
- :definition "It's foobar2000 actually"}]
+ (testing "Glossary entries are keyed on entity_id and carry the term"
+ (mt/with-temp [:model/Glossary {eid :entity_id} {:term "foobar"
+ :definition "It's foobar2000 actually"}]
(let [ser (serdes/extract-one "Glossary" {} (t2/select-one :model/Glossary :term "foobar"))]
- (is (=? {:serdes/meta [{:model "Glossary" :id "foobar"}]
- :term "foobar"}
+ (is (=? {:serdes/meta [{:model "Glossary" :id eid}]
+ :entity_id eid
+ :term "foobar"
+ :definition "It's foobar2000 actually"}
ser))))))
(deftest transform-tag-extraction-test
diff --git a/enterprise/backend/test/metabase_enterprise/serialization/v2/load_test.clj b/enterprise/backend/test/metabase_enterprise/serialization/v2/load_test.clj
index 22758f86a92..b22944da34f 100644
--- a/enterprise/backend/test/metabase_enterprise/serialization/v2/load_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/serialization/v2/load_test.clj
@@ -2982,3 +2982,64 @@
(is (= (:id data-dest) (:id data-after))))
(testing "permissions are unchanged after import"
(is (= perms-before perms-after))))))))))))
+
+(deftest glossary-round-trip-test
+ (let [serialized (atom nil)
+ eid (atom nil)]
+ (ts/with-dbs [source-db dest-db]
+ (ts/with-db source-db
+ (let [entry (ts/create! :model/Glossary :term "ARR" :definition "Annual recurring revenue")]
+ (reset! eid (:entity_id entry))
+ (reset! serialized (into [] (serdes.extract/extract {:no-settings true})))))
+ (testing "the export is keyed on entity_id"
+ (is (contains? (ids-by-model @serialized "Glossary") @eid)))
+ (testing "importing into an empty app db reproduces the term, definition and entity_id"
+ (ts/with-db dest-db
+ (serdes.load/load-metabase! (ingestion-in-memory @serialized))
+ (is (=? [{:term "ARR" :definition "Annual recurring revenue" :entity_id @eid}]
+ (t2/select :model/Glossary)))))
+ (testing "importing again updates in place rather than duplicating"
+ (ts/with-db dest-db
+ (serdes.load/load-metabase! (ingestion-in-memory @serialized))
+ (is (= 1 (t2/count :model/Glossary))))))))
+
+(deftest glossary-load-find-local-test
+ (mt/with-temp [:model/Glossary entry {:term "ARR" :definition "Annual recurring revenue"}]
+ (testing "an entity_id path finds the row"
+ (is (= (:id entry) (:id (serdes/load-find-local [{:model "Glossary" :id (:entity_id entry)}])))))
+ (testing "a term-keyed path from a pre-entity_id export finds the row"
+ (is (= (:id entry) (:id (serdes/load-find-local [{:model "Glossary" :id "ARR"}])))))
+ (testing "a term that is itself 21 nano-id characters still finds the row by term"
+ (mt/with-temp [:model/Glossary shaped {:term "CustomerLifetimeValue" :definition "x"}]
+ (is (= (:id shaped) (:id (serdes/load-find-local [{:model "Glossary" :id "CustomerLifetimeValue"}]))))))
+ (testing "an unknown term finds nothing"
+ (is (nil? (serdes/load-find-local [{:model "Glossary" :id "No such term"}]))))))
+
+(deftest glossary-import-matches-existing-term-test
+ (let [glossary-file (fn [id entity]
+ (merge {:serdes/meta [{:model "Glossary" :id id}]
+ :term "ARR"
+ :definition "Annual recurring revenue (imported)"
+ :creator_id "[email protected]"
+ :created_at "2026-09-11T00:00:00Z"
+ :updated_at "2026-09-11T00:00:00Z"}
+ entity))]
+ (testing "a term-keyed file exported before entity_id existed updates the same-term row and keeps its entity_id"
+ (mt/with-empty-h2-app-db!
+ (let [{local-eid :entity_id} (ts/create! :model/Glossary :term "ARR" :definition "local")]
+ (serdes.load/load-metabase! (ingestion-in-memory [(glossary-file "ARR" nil)]))
+ (is (=? [{:term "ARR" :definition "Annual recurring revenue (imported)" :entity_id local-eid}]
+ (t2/select :model/Glossary))))))
+ (testing "a file whose term exists locally under another entity_id updates that row in place and adopts the file's entity_id"
+ (mt/with-empty-h2-app-db!
+ (let [file-eid "glossaryfileeid000001"
+ {local-id :id} (ts/create! :model/Glossary :term "ARR" :definition "local")]
+ (serdes.load/load-metabase! (ingestion-in-memory [(glossary-file file-eid {:entity_id file-eid})]))
+ (is (=? [{:id local-id :term "ARR" :definition "Annual recurring revenue (imported)" :entity_id file-eid}]
+ (t2/select :model/Glossary))))))
+ (testing "a file whose entity_id and term are both new inserts a row"
+ (mt/with-empty-h2-app-db!
+ (let [file-eid "glossaryfileeid000002"]
+ (serdes.load/load-metabase! (ingestion-in-memory [(glossary-file file-eid {:entity_id file-eid})]))
+ (is (=? [{:term "ARR" :entity_id file-eid}]
+ (t2/select :model/Glossary))))))))
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/components/ChangesLists/AllChangesView.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/remote_sync/components/ChangesLists/AllChangesView.unit.spec.tsx
index c8b226746b7..3f3bfec6bae 100644
--- a/enterprise/frontend/src/metabase-enterprise/remote_sync/components/ChangesLists/AllChangesView.unit.spec.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/components/ChangesLists/AllChangesView.unit.spec.tsx
@@ -944,4 +944,52 @@ describe("AllChangesView", () => {
expect(screen.queryByText("Root")).not.toBeInTheDocument();
});
});
+
+ describe("glossary entries", () => {
+ it("should display glossary entries under the Library collection with the glossary icon", async () => {
+ const libraryCollection = createMockCollection({
+ id: 99,
+ name: "Library",
+ type: "library",
+ effective_ancestors: [],
+ });
+ const glossaryEntity = createMockRemoteSyncEntity({
+ id: 500,
+ name: "ARR",
+ model: "glossary",
+ collection_id: undefined,
+ sync_status: "create",
+ });
+
+ setup({
+ entities: [glossaryEntity],
+ collections: [libraryCollection],
+ });
+
+ expect(await screen.findByText("Library")).toBeInTheDocument();
+ expect(screen.getByText("ARR")).toBeInTheDocument();
+ expect(screen.getAllByLabelText("glossary icon").length).toBeGreaterThan(
+ 0,
+ );
+ expect(screen.queryByText("Root")).not.toBeInTheDocument();
+ });
+
+ it("should display glossary entries under Root when no Library collection exists", async () => {
+ const glossaryEntity = createMockRemoteSyncEntity({
+ id: 500,
+ name: "ARR",
+ model: "glossary",
+ collection_id: undefined,
+ sync_status: "update",
+ });
+
+ setup({
+ entities: [glossaryEntity],
+ collections: [defaultCollection],
+ });
+
+ expect(await screen.findByText("ARR")).toBeInTheDocument();
+ expect(screen.queryByText("Library")).not.toBeInTheDocument();
+ });
+ });
});
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/components/SyncConflictModal/SetupConflictInfo.tsx b/enterprise/frontend/src/metabase-enterprise/remote_sync/components/SyncConflictModal/SetupConflictInfo.tsx
index b0fda5d764e..d5d65b0dcce 100644
--- a/enterprise/frontend/src/metabase-enterprise/remote_sync/components/SyncConflictModal/SetupConflictInfo.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/components/SyncConflictModal/SetupConflictInfo.tsx
@@ -33,7 +33,7 @@ const useConflictedEntityNames = () => {
const names = [];
const conflictNameMap: Record<string, string> = {
transforms: t`Transforms`,
- snippets: t`Snippets`,
+ snippets: t`Snippets and glossary`,
library: t`Library`,
};
@@ -44,7 +44,7 @@ const useConflictedEntityNames = () => {
}
if (!names?.length) {
- return t`Library, Transforms and Snippets.`;
+ return t`Library, Transforms, Snippets and Glossary.`;
}
return names.join(", ");
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/displayGroups.ts b/enterprise/frontend/src/metabase-enterprise/remote_sync/displayGroups.ts
index 6fd23c171e7..d0cca765c93 100644
--- a/enterprise/frontend/src/metabase-enterprise/remote_sync/displayGroups.ts
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/displayGroups.ts
@@ -62,6 +62,13 @@ const displayGroupSpecs: DisplayGroupSpec[] = [
pathPrefixGroupId: "library",
priority: 90,
},
+ {
+ id: "glossary",
+ models: new Set(["glossary"]),
+ icon: "glossary",
+ pathPrefixGroupId: "library",
+ priority: 80,
+ },
{
id: "tables",
models: new Set(["table", "field", "segment", "measure"]),
@@ -170,7 +177,7 @@ const getGroupKeyInfo = (
if (entity.collection_id != null) {
return { groupKey: entity.collection_id, spec };
}
- if (spec.id === "snippets" && libraryCollectionId != null) {
+ if (spec.pathPrefixGroupId === "library" && libraryCollectionId != null) {
return { groupKey: libraryCollectionId, spec };
}
return { groupKey: 0, spec };
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-glossary-dirty-changes.ts b/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-glossary-dirty-changes.ts
new file mode 100644
index 00000000000..a052074d0c9
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-glossary-dirty-changes.ts
@@ -0,0 +1,16 @@
+import { useMemo } from "react";
+
+import { useGitSyncVisible } from "./use-git-sync-visible";
+import { useRemoteSyncDirtyState } from "./use-remote-sync-dirty-state";
+
+export function useHasGlossaryDirtyChanges(): boolean {
+ const { isVisible: isGitSyncVisible } = useGitSyncVisible();
+ const { dirty, isDirty } = useRemoteSyncDirtyState();
+
+ return useMemo(() => {
+ if (!isGitSyncVisible || !isDirty) {
+ return false;
+ }
+ return dirty.some((entity) => entity.model === "glossary");
+ }, [isGitSyncVisible, isDirty, dirty]);
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-glossary-dirty-changes.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-glossary-dirty-changes.unit.spec.ts
new file mode 100644
index 00000000000..15728370091
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-glossary-dirty-changes.unit.spec.ts
@@ -0,0 +1,94 @@
+import { setupEnterprisePlugins } from "__support__/enterprise";
+import {
+ setupPropertiesEndpoints,
+ setupRemoteSyncDirtyEndpoint,
+ setupSettingsEndpoints,
+} from "__support__/server-mocks";
+import { mockSettings } from "__support__/settings";
+import { createMockState } from "__support__/state";
+import { renderHookWithProviders, waitFor } from "__support__/ui";
+import type { RemoteSyncEntity } from "metabase-types/api";
+import {
+ createMockRemoteSyncEntity,
+ createMockSettings,
+ createMockTokenFeatures,
+ createMockUser,
+} from "metabase-types/api/mocks";
+
+import { useHasGlossaryDirtyChanges } from "./use-has-glossary-dirty-changes";
+
+interface SetupOptions {
+ isGitSyncVisible?: boolean;
+ dirty?: RemoteSyncEntity[];
+}
+
+const setup = ({ isGitSyncVisible = true, dirty = [] }: SetupOptions = {}) => {
+ setupEnterprisePlugins();
+
+ const tokenFeatures = createMockTokenFeatures({ library: true });
+ const settingsValues = {
+ "remote-sync-enabled": isGitSyncVisible,
+ "remote-sync-branch": isGitSyncVisible ? "main" : null,
+ "remote-sync-type": "read-write" as const,
+ "token-features": tokenFeatures,
+ };
+
+ setupPropertiesEndpoints(createMockSettings(settingsValues));
+ setupSettingsEndpoints([]);
+ setupRemoteSyncDirtyEndpoint({ dirty, changedCollections: {} });
+
+ const storeInitialState = createMockState({
+ currentUser: createMockUser({ is_superuser: true }),
+ settings: mockSettings(settingsValues),
+ });
+
+ return renderHookWithProviders(() => useHasGlossaryDirtyChanges(), {
+ storeInitialState,
+ });
+};
+
+const glossaryEntity = createMockRemoteSyncEntity({
+ id: 10,
+ name: "ARR",
+ model: "glossary",
+ sync_status: "create",
+});
+
+describe("useHasGlossaryDirtyChanges", () => {
+ it("returns false when no dirty changes exist", async () => {
+ const { result } = setup({ dirty: [] });
+
+ await waitFor(() => {
+ expect(result.current).toBe(false);
+ });
+ });
+
+ it("returns true when a glossary entry is dirty", async () => {
+ const { result } = setup({ dirty: [glossaryEntity] });
+
+ await waitFor(() => {
+ expect(result.current).toBe(true);
+ });
+ });
+
+ it("returns false when only non-glossary entities are dirty", async () => {
+ const { result } = setup({
+ dirty: [createMockRemoteSyncEntity({ model: "card", collection_id: 1 })],
+ });
+
+ await waitFor(() => {
+ expect(result.current).toBe(false);
+ });
+ });
+
+ it("returns false when git sync is not visible", async () => {
+ const { result } = setup({
+ isGitSyncVisible: false,
+ dirty: [glossaryEntity],
+ });
+
+ await waitFor(() => {
+ expect(result.current).toBe(false);
+ });
+ });
+});
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-library-dirty-changes.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-library-dirty-changes.unit.spec.ts
index 3123f29267d..9a0f2fa2a66 100644
--- a/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-library-dirty-changes.unit.spec.ts
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/hooks/use-has-library-dirty-changes.unit.spec.ts
@@ -326,4 +326,24 @@ describe("useHasLibraryDirtyChanges", () => {
});
});
});
+
+ describe("glossary dirty state", () => {
+ it("returns false for a dirty glossary entry because the Glossary tab carries its own badge", async () => {
+ const { result } = setup({
+ collections: [createLibraryCollection({ id: 1 })],
+ dirty: [
+ createMockDirtyEntity({
+ id: 10,
+ model: "glossary",
+ name: "ARR",
+ collection_id: undefined,
+ }),
+ ],
+ });
+
+ await waitFor(() => {
+ expect(result.current).toBe(false);
+ });
+ });
+ });
});
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/index.ts b/enterprise/frontend/src/metabase-enterprise/remote_sync/index.ts
index 23543656fbd..56dccc435d2 100644
--- a/enterprise/frontend/src/metabase-enterprise/remote_sync/index.ts
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/index.ts
@@ -17,6 +17,7 @@ import {
} from "./components/SyncedCollectionsSidebarSection";
import { REMOTE_SYNC_INVALIDATION_TAGS } from "./constants";
import { useGitSyncVisible } from "./hooks/use-git-sync-visible";
+import { useHasGlossaryDirtyChanges } from "./hooks/use-has-glossary-dirty-changes";
import { useHasLibraryDirtyChanges } from "./hooks/use-has-library-dirty-changes";
import { useHasTransformDirtyChanges } from "./hooks/use-has-transform-dirty-changes";
import { useRemoteSyncDirtyState } from "./hooks/use-remote-sync-dirty-state";
@@ -47,6 +48,7 @@ export function initializePlugin() {
PLUGIN_REMOTE_SYNC.useHasLibraryDirtyChanges = useHasLibraryDirtyChanges;
PLUGIN_REMOTE_SYNC.useHasTransformDirtyChanges =
useHasTransformDirtyChanges;
+ PLUGIN_REMOTE_SYNC.useHasGlossaryDirtyChanges = useHasGlossaryDirtyChanges;
PLUGIN_REMOTE_SYNC.getIsRemoteSyncReadOnly = getIsRemoteSyncReadOnly;
PLUGIN_REMOTE_SYNC.useRemoteSyncDirtyState = useRemoteSyncDirtyState;
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/middleware/model-configs.ts b/enterprise/frontend/src/metabase-enterprise/remote_sync/middleware/model-configs.ts
index 22216561265..7a25d239f6f 100644
--- a/enterprise/frontend/src/metabase-enterprise/remote_sync/middleware/model-configs.ts
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/middleware/model-configs.ts
@@ -5,6 +5,7 @@ import { collectionApi } from "metabase/api/collection";
import { dashboardApi } from "metabase/api/dashboard";
import { documentApi } from "metabase/api/document";
import { fieldApi } from "metabase/api/field";
+import { glossaryApi } from "metabase/api/glossary";
import { measureApi } from "metabase/api/measure";
import { segmentApi } from "metabase/api/segment";
import { snippetApi } from "metabase/api/snippet";
@@ -160,6 +161,13 @@ export const MODEL_MUTATION_CONFIGS: ModelMutationConfig[] = [
updateEndpoints: [snippetApi.endpoints.updateSnippet.matchFulfilled],
invalidation: { type: InvalidationType.Always },
},
+ {
+ modelType: "glossary",
+ createEndpoints: [glossaryApi.endpoints.createGlossary.matchFulfilled],
+ updateEndpoints: [glossaryApi.endpoints.updateGlossary.matchFulfilled],
+ deleteEndpoints: [glossaryApi.endpoints.deleteGlossary.matchFulfilled],
+ invalidation: { type: InvalidationType.Always },
+ },
{
modelType: "transform",
createEndpoints: [transformApi.endpoints.createTransform.matchFulfilled],
diff --git a/enterprise/frontend/src/metabase-enterprise/remote_sync/middleware/remote-sync-listener-middleware.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/remote_sync/middleware/remote-sync-listener-middleware.unit.spec.ts
index 954dddc3c5f..e53eb0faad1 100644
--- a/enterprise/frontend/src/metabase-enterprise/remote_sync/middleware/remote-sync-listener-middleware.unit.spec.ts
+++ b/enterprise/frontend/src/metabase-enterprise/remote_sync/middleware/remote-sync-listener-middleware.unit.spec.ts
@@ -14,6 +14,7 @@ import { Api } from "metabase/api";
import { cardApi } from "metabase/api/card";
import { collectionApi } from "metabase/api/collection";
import { dashboardApi } from "metabase/api/dashboard";
+import { glossaryApi } from "metabase/api/glossary";
import { remoteSyncApi } from "metabase-enterprise/api/remote-sync";
import type { EnterpriseSettings } from "metabase-types/api";
import {
@@ -669,4 +670,82 @@ describe("remote-sync-listener-middleware", () => {
expect(dirtyCallCount()).toBeGreaterThan(1);
});
});
+
+ describe("glossary listeners", () => {
+ afterEach(() => {
+ fetchMock.clearHistory();
+ });
+
+ const subscribeAndSettle = async (
+ store: ReturnType<typeof createTestStore>,
+ ) => {
+ store.dispatch(
+ remoteSyncApi.endpoints.getRemoteSyncChanges.initiate(undefined),
+ );
+ await waitForCondition(() =>
+ fetchMock.callHistory.done("remote-sync-dirty"),
+ );
+ };
+
+ const dirtyCallCount = () =>
+ fetchMock.callHistory.calls("remote-sync-dirty").length;
+
+ it("invalidates when a glossary entry is created", async () => {
+ fetchMock.post("path:/api/glossary", {
+ id: 1,
+ term: "ARR",
+ definition: "Annual recurring revenue",
+ });
+ setupRemoteSyncDirtyEndpoint();
+
+ const store = createTestStore();
+ await subscribeAndSettle(store);
+
+ store.dispatch(
+ glossaryApi.endpoints.createGlossary.initiate({
+ term: "ARR",
+ definition: "Annual recurring revenue",
+ }),
+ );
+
+ await waitForCondition(() => dirtyCallCount() > 1);
+ expect(dirtyCallCount()).toBeGreaterThan(1);
+ });
+
+ it("invalidates when a glossary entry is updated", async () => {
+ fetchMock.put("path:/api/glossary/1", {
+ id: 1,
+ term: "ARR",
+ definition: "Annualized recurring revenue",
+ });
+ setupRemoteSyncDirtyEndpoint();
+
+ const store = createTestStore();
+ await subscribeAndSettle(store);
+
+ store.dispatch(
+ glossaryApi.endpoints.updateGlossary.initiate({
+ id: 1,
+ term: "ARR",
+ definition: "Annualized recurring revenue",
+ }),
+ );
+
+ await waitForCondition(() => dirtyCallCount() > 1);
+ expect(dirtyCallCount()).toBeGreaterThan(1);
+ });
+
+ it("invalidates when a glossary entry is deleted", async () => {
+ fetchMock.delete("path:/api/glossary/1", 204);
+ setupRemoteSyncDirtyEndpoint();
+
+ const store = createTestStore();
+ await subscribeAndSettle(store);
+
+ store.dispatch(glossaryApi.endpoints.deleteGlossary.initiate({ id: 1 }));
+
+ await waitForCondition(() => dirtyCallCount() > 1);
+ expect(dirtyCallCount()).toBeGreaterThan(1);
+ });
+ });
});
diff --git a/frontend/src/metabase-types/api/remote-sync.ts b/frontend/src/metabase-types/api/remote-sync.ts
index af6d4b6349f..6564e2b2ce6 100644
--- a/frontend/src/metabase-types/api/remote-sync.ts
+++ b/frontend/src/metabase-types/api/remote-sync.ts
@@ -18,7 +18,8 @@ export type RemoteSyncEntityModel =
| "transform"
| "transformtag"
| "transformjob"
- | "pythonlibrary";
+ | "pythonlibrary"
+ | "glossary";
export type RemoteSyncEntityStatus =
| "create"
diff --git a/frontend/src/metabase/api/glossary.ts b/frontend/src/metabase/api/glossary.ts
index 97d1ed7f670..a576512a452 100644
--- a/frontend/src/metabase/api/glossary.ts
+++ b/frontend/src/metabase/api/glossary.ts
@@ -11,6 +11,12 @@ export type ListGlossaryRequest = {
search?: string;
};
+export type ListGlossaryResponse = {
+ data: GlossaryItem[];
+ /** Whether the current user may create, edit, or delete entries right now. */
+ can_write: boolean;
+};
+
export type CreateGlossaryRequest = {
term: string;
definition: string;
@@ -24,16 +30,18 @@ export type UpdateGlossaryRequest = {
export const glossaryApi = Api.injectEndpoints({
endpoints: (builder) => ({
- listGlossary: builder.query<GlossaryItem[], ListGlossaryRequest | void>({
+ listGlossary: builder.query<
+ ListGlossaryResponse,
+ ListGlossaryRequest | void
+ >({
query: (params) => ({
method: "GET",
url: "/api/glossary",
params,
}),
- transformResponse: (response: { data: GlossaryItem[] }) => response.data,
- providesTags: (items = []) => [
+ providesTags: (response) => [
listTag("glossary"),
- ...items.map((item) => idTag("glossary", item.id)),
+ ...(response?.data ?? []).map((item) => idTag("glossary", item.id)),
],
}),
createGlossary: builder.mutation<GlossaryItem, CreateGlossaryRequest>({
@@ -51,7 +59,7 @@ export const glossaryApi = Api.injectEndpoints({
undefined,
(draft) => {
// Add a temporary item to appear immediately
- draft.unshift({
+ draft.data.unshift({
id: tempId,
term: arg.term,
definition: arg.definition,
@@ -68,11 +76,11 @@ export const glossaryApi = Api.injectEndpoints({
"listGlossary",
undefined,
(draft) => {
- const idx = draft.findIndex((g) => g.id === tempId);
+ const idx = draft.data.findIndex((g) => g.id === tempId);
if (idx !== -1) {
- draft[idx] = data;
+ draft.data[idx] = data;
} else {
- draft.unshift(data);
+ draft.data.unshift(data);
}
},
),
@@ -98,7 +106,7 @@ export const glossaryApi = Api.injectEndpoints({
"listGlossary",
undefined,
(draft) => {
- const item = draft.find((g) => g.id === arg.id);
+ const item = draft.data.find((g) => g.id === arg.id);
if (item) {
item.term = arg.term;
item.definition = arg.definition;
@@ -134,9 +142,9 @@ export const glossaryApi = Api.injectEndpoints({
"listGlossary",
undefined,
(draft) => {
- const idx = draft.findIndex((g) => g.id === id);
+ const idx = draft.data.findIndex((g) => g.id === id);
if (idx !== -1) {
- draft.splice(idx, 1);
+ draft.data.splice(idx, 1);
}
},
),
diff --git a/frontend/src/metabase/common/utils/icon.ts b/frontend/src/metabase/common/utils/icon.ts
index fac0fec15c6..e2da2cf46d4 100644
--- a/frontend/src/metabase/common/utils/icon.ts
+++ b/frontend/src/metabase/common/utils/icon.ts
@@ -19,7 +19,8 @@ export type IconModel =
| "transform"
| "user"
| "nativequerysnippet"
- | "pythonlibrary";
+ | "pythonlibrary"
+ | "glossary";
export type ObjectWithModel = {
id?: unknown;
@@ -59,6 +60,7 @@ export const modelIconMap: Record<IconModel, IconName> = {
transform: "transform",
user: "person",
pythonlibrary: "code_block",
+ glossary: "glossary",
exploration: "telescope",
};
diff --git a/frontend/src/metabase/data-studio/app/pages/DataStudioLayout/DataStudioLayout.tsx b/frontend/src/metabase/data-studio/app/pages/DataStudioLayout/DataStudioLayout.tsx
index 93b1714ccb1..881983508c0 100644
--- a/frontend/src/metabase/data-studio/app/pages/DataStudioLayout/DataStudioLayout.tsx
+++ b/frontend/src/metabase/data-studio/app/pages/DataStudioLayout/DataStudioLayout.tsx
@@ -39,6 +39,8 @@ export function DataStudioLayout() {
const hasDirtyChanges = PLUGIN_REMOTE_SYNC.useHasLibraryDirtyChanges();
const hasTransformDirtyChanges =
PLUGIN_REMOTE_SYNC.useHasTransformDirtyChanges();
+ const hasGlossaryDirtyChanges =
+ PLUGIN_REMOTE_SYNC.useHasGlossaryDirtyChanges();
const [isGitSettingsOpen, setIsGitSettingsOpen] = useState(false);
const hasLibraryFeature = useHasTokenFeature("library");
@@ -113,6 +115,12 @@ export function DataStudioLayout() {
to={Urls.dataStudioGlossary()}
isSelected={currentTab === "glossary"}
showLabel={isNavbarOpened}
+ rightSection={
+ hasGlossaryDirtyChanges &&
+ PLUGIN_REMOTE_SYNC.CollectionSyncStatusBadge ? (
+ <PLUGIN_REMOTE_SYNC.CollectionSyncStatusBadge />
+ ) : null
+ }
/>
</AreaTabGroup>
diff --git a/frontend/src/metabase/data-studio/glossary/pages/GlossaryPage/GlossaryPage.tsx b/frontend/src/metabase/data-studio/glossary/pages/GlossaryPage/GlossaryPage.tsx
index 90f8a4f03d7..d21a245669c 100644
--- a/frontend/src/metabase/data-studio/glossary/pages/GlossaryPage/GlossaryPage.tsx
+++ b/frontend/src/metabase/data-studio/glossary/pages/GlossaryPage/GlossaryPage.tsx
@@ -22,7 +22,9 @@ import S from "./GlossaryPage.module.css";
export function GlossaryPage() {
usePageTitle(t`Glossary`);
- const { data: glossary = [] } = useListGlossaryQuery();
+ const { data } = useListGlossaryQuery();
+ const glossary = data?.data ?? [];
+ const canWrite = data?.can_write ?? false;
const [createGlossary] = useCreateGlossaryMutation();
const [updateGlossary] = useUpdateGlossaryMutation();
const [deleteGlossary] = useDeleteGlossaryMutation();
@@ -38,6 +40,7 @@ export function GlossaryPage() {
<Card px="xl" pb="sm" withBorder shadow="none">
<GlossaryTable
glossary={glossary}
+ readOnly={!canWrite}
onCreate={async (term, definition) => {
const { data } = await createGlossary({ term, definition });
if (data?.id) {
diff --git a/frontend/src/metabase/data-studio/glossary/pages/GlossaryPage/GlossaryPage.unit.spec.tsx b/frontend/src/metabase/data-studio/glossary/pages/GlossaryPage/GlossaryPage.unit.spec.tsx
new file mode 100644
index 00000000000..52ee2a60b5d
--- /dev/null
+++ b/frontend/src/metabase/data-studio/glossary/pages/GlossaryPage/GlossaryPage.unit.spec.tsx
@@ -0,0 +1,51 @@
+import userEvent from "@testing-library/user-event";
+import fetchMock from "fetch-mock";
+
+import { renderWithProviders, screen } from "__support__/ui";
+import type { ListGlossaryResponse } from "metabase/api";
+
+import { GlossaryPage } from "./GlossaryPage";
+
+jest.mock("metabase/nav/components/AppSwitcher", () => ({
+ AppSwitcher: () => <div data-testid="app-switcher" />,
+}));
+
+function setup({ can_write }: Pick<ListGlossaryResponse, "can_write">) {
+ const response: ListGlossaryResponse = {
+ data: [{ id: 1, term: "ARR", definition: "Annual recurring revenue" }],
+ can_write,
+ };
+ fetchMock.get("path:/api/glossary", response);
+
+ renderWithProviders(<GlossaryPage />, { withRouter: true });
+}
+
+describe("GlossaryPage", () => {
+ it("hides the add button and row edit controls when the glossary is not writable", async () => {
+ setup({ can_write: false });
+
+ expect(await screen.findByText("ARR")).toBeInTheDocument();
+ expect(
+ screen.queryByRole("button", { name: /new term/i }),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole("button", { name: /delete/i }),
+ ).not.toBeInTheDocument();
+
+ await userEvent.click(screen.getByText("ARR"));
+ expect(screen.queryByPlaceholderText("Boat")).not.toBeInTheDocument();
+ });
+
+ it("shows the add button and row edit controls when the glossary is writable", async () => {
+ setup({ can_write: true });
+
+ expect(await screen.findByText("ARR")).toBeInTheDocument();
+ expect(
+ screen.getByRole("button", { name: /new term/i }),
+ ).toBeInTheDocument();
+ expect(screen.getByRole("button", { name: /delete/i })).toBeInTheDocument();
+
+ await userEvent.click(screen.getByText("ARR"));
+ expect(screen.getByPlaceholderText("Boat")).toBeInTheDocument();
+ });
+});
diff --git a/frontend/src/metabase/plugins/oss/remote-sync.ts b/frontend/src/metabase/plugins/oss/remote-sync.ts
index 759929b4f1d..55837be3aa0 100644
--- a/frontend/src/metabase/plugins/oss/remote-sync.ts
+++ b/frontend/src/metabase/plugins/oss/remote-sync.ts
@@ -83,6 +83,7 @@ const getDefaultPluginRemoteSync = () => ({
useGitSyncVisible: () => ({ isVisible: false, currentBranch: null }),
useHasLibraryDirtyChanges: () => false,
useHasTransformDirtyChanges: () => false,
+ useHasGlossaryDirtyChanges: () => false,
getIsRemoteSyncReadOnly: () => false,
useRemoteSyncDirtyState: () =>
// Unjustified type cast. FIXME
@@ -115,6 +116,7 @@ export const PLUGIN_REMOTE_SYNC: {
};
useHasLibraryDirtyChanges: () => boolean;
useHasTransformDirtyChanges: () => boolean;
+ useHasGlossaryDirtyChanges: () => boolean;
getIsRemoteSyncReadOnly: (state: State) => boolean;
useRemoteSyncDirtyState: () => RemoteSyncDirtyState;
} = definePluginSlot(getDefaultPluginRemoteSync);
diff --git a/frontend/src/metabase/reference/glossary/GlossaryContainer.tsx b/frontend/src/metabase/reference/glossary/GlossaryContainer.tsx
index cd29ce37f10..0de2beb4f13 100644
--- a/frontend/src/metabase/reference/glossary/GlossaryContainer.tsx
+++ b/frontend/src/metabase/reference/glossary/GlossaryContainer.tsx
@@ -10,20 +10,17 @@ import {
import S from "metabase/common/components/Glossary/Glossary.module.css";
import { GlossaryTable } from "metabase/common/components/Glossary/GlossaryTable";
import CS from "metabase/css/core/index.css";
-import { getUserIsAdmin, getUserIsAnalyst } from "metabase/current-user";
-import { useSelector } from "metabase/redux";
import { SidebarLayout } from "metabase/reference/components/SidebarLayout";
import BaseSidebar from "metabase/reference/guide/BaseSidebar";
import { Card, Group, Stack, Text } from "metabase/ui";
export function GlossaryContainer() {
- const { data: glossary = [] } = useListGlossaryQuery();
+ const { data } = useListGlossaryQuery();
+ const glossary = data?.data ?? [];
+ const canWrite = data?.can_write ?? false;
const [createGlossary] = useCreateGlossaryMutation();
const [updateGlossary] = useUpdateGlossaryMutation();
const [deleteGlossary] = useDeleteGlossaryMutation();
- const isAdmin = useSelector(getUserIsAdmin);
- const isAnalyst = useSelector(getUserIsAnalyst);
- const canManage = isAdmin || isAnalyst;
return (
<SidebarLayout
@@ -51,7 +48,7 @@ export function GlossaryContainer() {
<GlossaryTable
className={S.table}
glossary={glossary}
- readOnly={!canManage}
+ readOnly={!canWrite}
onCreate={async (term, definition) => {
await createGlossary({ term, definition });
}}
diff --git a/frontend/src/metabase/urls/modelToUrl.ts b/frontend/src/metabase/urls/modelToUrl.ts
index f47cb6f604e..d666b893eba 100644
--- a/frontend/src/metabase/urls/modelToUrl.ts
+++ b/frontend/src/metabase/urls/modelToUrl.ts
@@ -12,7 +12,10 @@ import { browseDatabase } from "./browse";
import { card } from "./cards";
import { collection } from "./collections";
import { dashboard } from "./dashboards";
-import { dataStudioPublishedTableMeasure } from "./data-studio";
+import {
+ dataStudioGlossary,
+ dataStudioPublishedTableMeasure,
+} from "./data-studio";
import { document } from "./documents";
import { indexedEntity } from "./indexed-entities";
import { metric } from "./metrics";
@@ -96,6 +99,8 @@ export function modelToUrl(item: UrlableModel): string {
return NOT_FOUND_URL;
case "exploration":
return exploration(item.id);
+ case "glossary":
+ return dataStudioGlossary();
default:
return NOT_FOUND_URL;
}
diff --git a/resources/migrations/065/20260911_glossary_entity_id.yaml b/resources/migrations/065/20260911_glossary_entity_id.yaml
new file mode 100644
index 00000000000..29773de7dde
--- /dev/null
+++ b/resources/migrations/065/20260911_glossary_entity_id.yaml
@@ -0,0 +1,63 @@
+## Glossary entries get an entity_id so serialization and remote sync can key them on a stable, portable
+## identifier instead of the (renameable, per-instance) term. Backfill mirrors 20260723_backfill_entity_ids:
+## all three dialect variants in one changeset so every database records it, then NOT NULL and UNIQUE.
+
+databaseChangeLog:
+ - changeSet:
+ id: v65.2026-09-11T12:00:00
+ author: tplude
+ comment: Add entity_id column to glossary table
+ changes:
+ - addColumn:
+ tableName: glossary
+ columns:
+ - column:
+ name: entity_id
+ type: char(21)
+ remarks: Random NanoID tag for unique identity.
+ constraints:
+ nullable: true
+ rollback:
+ - dropColumn:
+ tableName: glossary
+ columnName: entity_id
+
+ - changeSet:
+ id: v65.2026-09-11T12:00:01
+ author: tplude
+ comment: Backfill NULL glossary.entity_id values
+ changes:
+ - sql:
+ dbms: postgresql
+ sql: UPDATE glossary SET entity_id = substr(replace(gen_random_uuid()::text, '-', ''), 1, 21) WHERE entity_id IS NULL;
+ - sql:
+ dbms: mysql,mariadb
+ sql: UPDATE glossary SET entity_id = substr(replace(uuid(), '-', ''), 1, 21) WHERE entity_id IS NULL;
+ - sql:
+ dbms: h2
+ sql: UPDATE glossary SET entity_id = substr(replace(cast(random_uuid() as varchar), '-', ''), 1, 21) WHERE entity_id IS NULL;
+ rollback: []
+
+ - changeSet:
+ id: v65.2026-09-11T12:00:02
+ author: tplude
+ comment: entity_id is NOT NULL on glossary
+ changes:
+ - addNotNullConstraint:
+ tableName: glossary
+ columnName: entity_id
+ columnDataType: char(21)
+
+ - changeSet:
+ id: v65.2026-09-11T12:00:03
+ author: tplude
+ comment: entity_id is unique on glossary
+ changes:
+ - addUniqueConstraint:
+ tableName: glossary
+ columnNames: entity_id
+ constraintName: uq_glossary_entity_id
+ rollback:
+ - dropUniqueConstraint:
+ tableName: glossary
+ constraintName: uq_glossary_entity_id
diff --git a/src/metabase/glossary/api.clj b/src/metabase/glossary/api.clj
index 0d98d413eb8..d8afac1f2db 100644
--- a/src/metabase/glossary/api.clj
+++ b/src/metabase/glossary/api.clj
@@ -3,11 +3,20 @@
(:require
[metabase.api.common :as api]
[metabase.api.macros :as api.macros]
- [metabase.events.core :as events]
+ [metabase.glossary.core :as glossary.core]
[metabase.glossary.db :as glossary.db]
+ [metabase.remote-sync.core :as remote-sync]
[metabase.util.malli.schema :as ms]
[toucan2.core :as t2]))
+(defn- editable?
+ "Glossary entries are locked on a read-only remote-sync instance whose Library is synced."
+ []
+ (remote-sync/model-editable? :model/Glossary nil))
+
+(defn- check-editable! []
+ (api/check-403 (editable?)))
+
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
;;
@@ -16,7 +25,8 @@
"Fetch all glossary entries, optionally filtered by search term."
[_route-params
{:keys [search]} :- [:maybe [:map {:closed true} [:search {:optional true} [:maybe ms/NonBlankString]]]]]
- {:data (t2/hydrate (glossary.db/glossary-entries search) :creator)})
+ {:data (t2/hydrate (glossary.db/glossary-entries search) :creator)
+ :can_write (boolean (and (api/is-data-analyst?) (editable?)))})
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
@@ -26,18 +36,12 @@
"Create a new glossary entry."
[_route-params
_query-params
- {:keys [term definition]} :- [:map {:closed true}
- [:term ms/NonBlankString]
- [:definition ms/NonBlankString]]]
+ body :- [:map {:closed true}
+ [:term ms/NonBlankString]
+ [:definition ms/NonBlankString]]]
(api/check-data-analyst)
- (let [glossary (glossary.db/insert-glossary-entry!
- {:term term
- :definition definition
- :creator_id api/*current-user-id*})]
- (events/publish-event! :event/glossary-create
- {:object glossary
- :user-id api/*current-user-id*})
- (t2/hydrate glossary :creator)))
+ (check-editable!)
+ (t2/hydrate (glossary.core/create-entry! api/*current-user-id* body) :creator))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
@@ -47,18 +51,12 @@
"Update an existing glossary entry."
[{:keys [id]} :- [:map {:closed true} [:id ms/PositiveInt]]
_query-params
- {:keys [term definition]} :- [:map {:closed true}
- [:term ms/NonBlankString]
- [:definition ms/NonBlankString]]]
+ body :- [:map {:closed true}
+ [:term ms/NonBlankString]
+ [:definition ms/NonBlankString]]]
(api/check-data-analyst)
- (let [previous-glossary (api/check-404 (glossary.db/glossary-entry id))]
- (glossary.db/update-glossary-entry! id term definition)
- (let [glossary (glossary.db/glossary-entry id)]
- (events/publish-event! :event/glossary-update
- {:object glossary
- :previous-object previous-glossary
- :user-id api/*current-user-id*})
- (t2/hydrate glossary :creator))))
+ (check-editable!)
+ (t2/hydrate (api/check-404 (glossary.core/update-entry! api/*current-user-id* id body)) :creator))
;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to
;; use our API + we will need it when we make auto-TypeScript-signature generation happen
@@ -68,9 +66,6 @@
"Delete a glossary entry."
[{:keys [id]} :- [:map {:closed true} [:id ms/PositiveInt]]]
(api/check-data-analyst)
- (let [glossary (api/check-404 (glossary.db/glossary-entry id))]
- (glossary.db/delete-glossary-entry! id)
- (events/publish-event! :event/glossary-delete
- {:object glossary
- :user-id api/*current-user-id*}))
+ (check-editable!)
+ (api/check-404 (glossary.core/delete-entry! api/*current-user-id* id))
api/generic-204-no-content)
diff --git a/src/metabase/glossary/core.clj b/src/metabase/glossary/core.clj
new file mode 100644
index 00000000000..2a2ecea3eee
--- /dev/null
+++ b/src/metabase/glossary/core.clj
@@ -0,0 +1,50 @@
+(ns metabase.glossary.core
+ "API namespace for the glossary module. Every glossary write goes through here so that each one publishes its
+ `:event/glossary-*` event regardless of the caller (REST API, MCP tools, and so on)."
+ (:require
+ [metabase.events.core :as events]
+ [metabase.glossary.db :as glossary.db]
+ [metabase.glossary.schema :as glossary.schema]
+ [metabase.lib.schema.id :as lib.schema.id]
+ [metabase.util.malli :as mu]
+ [metabase.util.malli.registry :as mr]
+ [metabase.util.malli.schema :as ms]))
+
+(mr/def ::entry-fields
+ [:map {:closed true}
+ [:term ms/NonBlankString]
+ [:definition ms/NonBlankString]])
+
+(mu/defn create-entry! :- ::glossary.schema/glossary
+ "Insert a glossary entry created by `user-id` and publish `:event/glossary-create`. Returns the new entry."
+ [user-id :- ::lib.schema.id/user
+ {:keys [term definition]} :- ::entry-fields]
+ (let [entry (glossary.db/insert-glossary-entry! {:term term
+ :definition definition
+ :creator_id user-id})]
+ (events/publish-event! :event/glossary-create {:object entry :user-id user-id})
+ entry))
+
+(mu/defn update-entry! :- [:maybe ::glossary.schema/glossary]
+ "Set the term and definition of the glossary entry with `id` on behalf of `user-id` and publish
+ `:event/glossary-update`. Returns the updated entry, or nil when no entry has `id`."
+ [user-id :- ::lib.schema.id/user
+ id :- ms/PositiveInt
+ {:keys [term definition]} :- ::entry-fields]
+ (when-let [previous (glossary.db/glossary-entry id)]
+ (glossary.db/update-glossary-entry! id term definition)
+ (let [entry (glossary.db/glossary-entry id)]
+ (events/publish-event! :event/glossary-update {:object entry
+ :previous-object previous
+ :user-id user-id})
+ entry)))
+
+(mu/defn delete-entry! :- [:maybe ::glossary.schema/glossary]
+ "Delete the glossary entry with `id` on behalf of `user-id` and publish `:event/glossary-delete`. Returns the
+ deleted entry, or nil when no entry has `id`."
+ [user-id :- ::lib.schema.id/user
+ id :- ms/PositiveInt]
+ (when-let [entry (glossary.db/glossary-entry id)]
+ (glossary.db/delete-glossary-entry! id)
+ (events/publish-event! :event/glossary-delete {:object entry :user-id user-id})
+ entry))
diff --git a/src/metabase/glossary/models/glossary.clj b/src/metabase/glossary/models/glossary.clj
index abc67dc15b4..0a31c583811 100644
--- a/src/metabase/glossary/models/glossary.clj
+++ b/src/metabase/glossary/models/glossary.clj
@@ -11,7 +11,8 @@
(doto :model/Glossary
(derive :metabase/model)
- (derive :hook/timestamped?))
+ (derive :hook/timestamped?)
+ (derive :hook/entity-id))
(methodical/defmethod t2/batched-hydrate [:model/Glossary :creator]
"Add creator (user) to a glossary entry"
@@ -32,18 +33,31 @@
;;; ---------------------- Serialization ----------------------------
-(defmethod serdes/entity-id "Glossary" [_ {:keys [term]}]
- term)
-
(defmethod serdes/load-find-local "Glossary"
[path]
- (glossary.db/glossary-entry-by-term (:id (first path))))
+ ;; Files exported before `entity_id` existed are keyed by term, and a term can itself be 21 nano-id characters,
+ ;; so try both lookups rather than discriminating on shape.
+ (let [{:keys [id]} (last path)]
+ (or (serdes/lookup-by-id :model/Glossary id)
+ (glossary.db/glossary-entry-by-term id))))
+
+(defmethod serdes/load-one! "Glossary"
+ [ingested maybe-local]
+ ;; `term` is unique, so a file whose entity_id matches no local row is matched on its term instead: two instances
+ ;; can each create the same term under different entity_ids. That local row is updated in place (same primary
+ ;; key) and adopts the file's entity_id and definition; its own entity_id is discarded, nothing references it.
+ ;; A term-keyed file (exported before entity_id existed) gets a throwaway entity_id from the loader, so the local
+ ;; row keeps its identity in that case.
+ (let [local (or maybe-local (glossary.db/glossary-entry-by-term (:term ingested)))
+ term-keyed? (not= (-> ingested serdes/path last :id) (:entity_id ingested))]
+ (serdes/default-load-one! (cond-> ingested
+ (and local term-keyed?) (assoc :entity_id (:entity_id local)))
+ local)))
(defmethod serdes/make-spec "Glossary" [_model-name _opts]
- {:copy [:term :definition]
+ {:copy [:entity_id :term :definition]
:transform {:created_at (serdes/date)
- :updated_at (serdes/date)
:creator_id (serdes/fk :model/User)}})
(defmethod serdes/storage-path "Glossary" [item _]
- [{:label "glossary"} {:label (:term item) :key (:term item)}])
+ [{:label "glossary"} {:label (:term item) :key (:entity_id item)}])
diff --git a/src/metabase/glossary/schema.clj b/src/metabase/glossary/schema.clj
index 03863b693ba..b5cbc3b7889 100644
--- a/src/metabase/glossary/schema.clj
+++ b/src/metabase/glossary/schema.clj
@@ -15,6 +15,7 @@
(mr/def ::glossary.update
"What an update (or insert) of a Glossary accepts: every column of `:glossary` except `id`, all optional."
[:map {:closed true}
+ [:entity_id {:optional true} [:maybe ms/NonBlankString]]
[:term {:optional true} [:maybe :string]]
[:definition {:optional true} [:maybe :string]]
[:created_at {:optional true} [:maybe ms/TemporalInstant]]
diff --git a/src/metabase/remote_sync/events.clj b/src/metabase/remote_sync/events.clj
index 9111cac765d..03180743328 100644
--- a/src/metabase/remote_sync/events.clj
+++ b/src/metabase/remote_sync/events.clj
@@ -28,6 +28,12 @@
;; Snippet events are derived in the the ...models.native-query-snippet interface
;; with some indirection
+;; Glossary events
+(events/derive! ::glossary-event :metabase/event)
+(events/derive! :event/glossary-create ::glossary-event)
+(events/derive! :event/glossary-update ::glossary-event)
+(events/derive! :event/glossary-delete ::glossary-event)
+
;; Transform Tag events
(events/derive! ::transform-tag-event :metabase/event)
(events/derive! :event/transform-tag-create ::transform-tag-event)
diff --git a/test/metabase/app_db/schema_migrations_test.clj b/test/metabase/app_db/schema_migrations_test.clj
index 061fde19f6b..f5ace6c1f42 100644
--- a/test/metabase/app_db/schema_migrations_test.clj
+++ b/test/metabase/app_db/schema_migrations_test.clj
@@ -3406,3 +3406,27 @@
(testing "only the columns that are non-NULL are flagged true"
(is (=? {:description_set true, :semantic_type_set false, :fk_target_field_id_set false}
(t2/select-one :metabase_field_user_settings :field_id mixed-id))))))))
+
+(deftest glossary-entity-id-backfill-test
+ (testing "v65.2026-09-11: glossary.entity_id is added, backfilled for existing rows, NOT NULL and unique"
+ (impl/test-migrations ["v65.2026-09-11T12:00:00" "v65.2026-09-11T12:00:03"] [migrate!]
+ (let [row (fn [term] {:term term
+ :definition (str term " definition")
+ :creator_id 13371338
+ :created_at :%now
+ :updated_at :%now})
+ arr-id (t2/insert-returning-pk! :glossary (row "ARR"))
+ churn-id (t2/insert-returning-pk! :glossary (row "Churn"))]
+ (migrate!)
+ (let [arr-eid (t2/select-one-fn :entity_id :glossary :id arr-id)
+ churn-eid (t2/select-one-fn :entity_id :glossary :id churn-id)]
+ (testing "existing rows receive distinct 21-character entity_ids"
+ (is (= 21 (count arr-eid)))
+ (is (= 21 (count churn-eid)))
+ (is (not= arr-eid churn-eid)))
+ (testing "entity_id is NOT NULL"
+ (is (thrown? Exception
+ (t2/insert! :glossary (assoc (row "MRR") :entity_id nil)))))
+ (testing "entity_id is unique"
+ (is (thrown? Exception
+ (t2/insert! :glossary (assoc (row "NRR") :entity_id arr-eid))))))))))
diff --git a/test/metabase/glossary/api_test.clj b/test/metabase/glossary/api_test.clj
index a9da8909dae..6f7cd21efaa 100644
--- a/test/metabase/glossary/api_test.clj
+++ b/test/metabase/glossary/api_test.clj
@@ -115,13 +115,16 @@
(testing "the entry was not modified"
(is (=? {:term "Existing" :definition "An existing entry"}
(t2/select-one :model/Glossary :id gid)))))
- (testing "regular users can still read the glossary"
- (is (mt/user-http-request :rasta :get 200 "glossary")))))
+ (testing "regular users can still read the glossary, and the response reports it as not writable"
+ (is (false? (:can_write (mt/user-http-request :rasta :get 200 "glossary")))))
+ (testing "superusers see the glossary as writable"
+ (is (true? (:can_write (mt/user-http-request :crowberto :get 200 "glossary")))))))
(testing "data analysts can mutate the glossary"
(mt/with-model-cleanup [:model/Glossary]
(mt/with-temp [:model/User {analyst-id :id} {:is_data_analyst true}
:model/PermissionsGroupMembership _ {:user_id analyst-id
:group_id (:id (perms-group/data-analyst))}]
+ (is (true? (:can_write (mt/user-http-request analyst-id :get 200 "glossary"))))
(let [{gid :id} (mt/user-http-request analyst-id :post 200 "glossary"
{:term "Analyst" :definition "Created by analyst"})]
(is (pos-int? gid))
diff --git a/test/metabase/glossary/core_test.clj b/test/metabase/glossary/core_test.clj
new file mode 100644
index 00000000000..2884132e4ae
--- /dev/null
+++ b/test/metabase/glossary/core_test.clj
@@ -0,0 +1,79 @@
+(ns metabase.glossary.core-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.events.core :as events]
+ [metabase.glossary.core :as glossary.core]
+ [metabase.test :as mt]
+ [methodical.core :as methodical]
+ [toucan2.core :as t2]))
+
+;; `publish-event!` is a methodical multimethod, so capture events with a handler on a test-only parent topic
+;; rather than by redefining the var (see the docstring of [[metabase.events.impl/publish-event!]]).
+
+(def ^:private ^:dynamic *events* nil)
+
+(events/derive! ::glossary-test-event :metabase/event)
+(events/derive! :event/glossary-create ::glossary-test-event)
+(events/derive! :event/glossary-update ::glossary-test-event)
+(events/derive! :event/glossary-delete ::glossary-test-event)
+
+(methodical/defmethod events/publish-event! ::glossary-test-event
+ [topic event]
+ (when *events*
+ (swap! *events* conj {:topic topic :event event})))
+
+(defn- with-captured-events!
+ "Call `f` with glossary events captured. Returns `{:result (f) :events [{:topic :event} ...]}`."
+ [f]
+ (binding [*events* (atom [])]
+ {:result (f)
+ :events @*events*}))
+
+(deftest create-entry-test
+ (mt/with-model-cleanup [:model/Glossary]
+ (let [user-id (mt/user->id :rasta)
+ {entry :result events :events} (with-captured-events!
+ #(glossary.core/create-entry! user-id {:term "ARR"
+ :definition "Annual recurring revenue"}))]
+ (testing "the row is inserted with the creator and returned"
+ (is (=? {:term "ARR" :definition "Annual recurring revenue" :creator_id user-id} entry))
+ (is (= entry (t2/select-one :model/Glossary :id (:id entry)))))
+ (testing "exactly one create event is published with the new entry and the user"
+ (is (= [{:topic :event/glossary-create
+ :event {:object entry :user-id user-id}}]
+ events))))))
+
+(deftest update-entry-test
+ (let [user-id (mt/user->id :rasta)]
+ (mt/with-temp [:model/Glossary {id :id} {:term "ARR" :definition "old"}]
+ (let [{entry :result events :events} (with-captured-events!
+ #(glossary.core/update-entry! user-id id {:term "NRR" :definition "new"}))]
+ (testing "the row is updated and returned"
+ (is (=? {:id id :term "NRR" :definition "new"} entry))
+ (is (= entry (t2/select-one :model/Glossary :id id))))
+ (testing "exactly one update event is published with the new and previous entries"
+ (is (= 1 (count events)))
+ (is (=? {:topic :event/glossary-update
+ :event {:object entry
+ :previous-object {:id id :term "ARR" :definition "old"}
+ :user-id user-id}}
+ (first events))))))
+ (testing "a missing id returns nil and publishes nothing"
+ (is (= {:result nil :events []}
+ (with-captured-events!
+ #(glossary.core/update-entry! user-id Integer/MAX_VALUE {:term "x" :definition "y"})))))))
+
+(deftest delete-entry-test
+ (let [user-id (mt/user->id :rasta)]
+ (mt/with-temp [:model/Glossary {id :id :as entry} {:term "ARR" :definition "Annual recurring revenue"}]
+ (let [{deleted :result events :events} (with-captured-events! #(glossary.core/delete-entry! user-id id))]
+ (testing "the row is deleted and returned"
+ (is (= entry deleted))
+ (is (nil? (t2/select-one :model/Glossary :id id))))
+ (testing "exactly one delete event is published with the deleted entry"
+ (is (= [{:topic :event/glossary-delete
+ :event {:object entry :user-id user-id}}]
+ events)))))
+ (testing "a missing id returns nil and publishes nothing"
+ (is (= {:result nil :events []}
+ (with-captured-events! #(glossary.core/delete-entry! user-id Integer/MAX_VALUE)))))))
diff --git a/test_resources/serialization_baseline/glossary/foobar.yaml b/test_resources/serialization_baseline/glossary/foobar.yaml
index 1ed65db0cd9..ce81506fc85 100644
--- a/test_resources/serialization_baseline/glossary/foobar.yaml
+++ b/test_resources/serialization_baseline/glossary/foobar.yaml
@@ -1,8 +1,8 @@
created_at: '2025-09-18T13:38:26.721389Z'
creator_id: [email protected]
definition: It's foobar2000 actually
+entity_id: fooBar2000gLossary001
term: foobar
-updated_at: '2025-09-18T13:38:26.721389Z'
serdes/meta:
-- id: foobar
+- id: fooBar2000gLossary001
model: Glossary