The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
feat(search): publish analytics for every search context (#76613)
Chris Truter705bda8519ff
diff --git a/frontend/src/metabase-types/analytics/search.ts b/frontend/src/metabase-types/analytics/search.tsindex b578e45e25e..b49a535d79c 100644--- a/frontend/src/metabase-types/analytics/search.ts+++ b/frontend/src/metabase-types/analytics/search.ts@@ -1,4 +1,4 @@-import type { SearchContext, SearchModel } from "metabase-types/api";+import type { SearchContext } from "metabase-types/api";type SearchEventSchema = {event: string;@@ -31,7 +31,8 @@ type ValidateEvent<> = T;// The snowplow `search` schema's `content_type` enum; keep in sync with-// snowplow/iglu-client-embedded/schemas/com.metabase/search/jsonschema/1-1-3+// snowplow/iglu-client-embedded/schemas/com.metabase/search/jsonschema/1-1-4+// "other" (kept last) is the catch-all bucket for models that aren't tracked content types.const SNOWPLOW_CONTENT_TYPES = ["dashboard","card",@@ -46,47 +47,51 @@ const SNOWPLOW_CONTENT_TYPES = ["indexed-entity","document","transform",+ "other",] as const;type SearchContentType = (typeof SNOWPLOW_CONTENT_TYPES)[number];const SNOWPLOW_CONTENT_TYPE_SET = new Set<string>(SNOWPLOW_CONTENT_TYPES);-// Maps a search request's `models` to snowplow `content_type`, de-duplicating and dropping any model-// that isn't a tracked content type. Today every `SearchModel` is a tracked content type, so nothing is-// dropped; the follow-up that adds the `"other"` bucket (and schema 1-1-4) will route untracked there.+const isSearchContentType = (model: string): model is SearchContentType =>+ SNOWPLOW_CONTENT_TYPE_SET.has(model);++// Maps arbitrary model strings to snowplow `content_type`, bucketing untracked values into "other"+// and de-duplicating.export const toSnowplowContentTypes = (- models: SearchModel[] | null | undefined,+ models: string[] | null | undefined,): SearchContentType[] | null =>models == null? null- : Array.from(new Set(models)).filter((model): model is SearchContentType =>- SNOWPLOW_CONTENT_TYPE_SET.has(model),+ : Array.from(+ new Set(+ models.map((model) => (isSearchContentType(model) ? model : "other")),+ ),);// The snowplow `search` schema's `context` enum; keep in sync with-// snowplow/iglu-client-embedded/schemas/com.metabase/search/jsonschema/1-1-3-// Only the surfaces already in the schema are published. Every other `SearchContext` is listed in-// `PENDING_CONTEXTS` and suppressed (emitted as `null`) until the iglu schema is widened — see the-// stacked follow-up that adds schema 1-1-4 and an `"other"` catch-all bucket.+// snowplow/iglu-client-embedded/schemas/com.metabase/search/jsonschema/1-1-4+// Add a new UI context here (and to iglu), or to `PENDING_CONTEXTS` to emit it as "other" until iglu catches up.+// Kept nullable on the wire (though always sent non-null) to avoid a MODEL version bump that forks events to a new table.type SnowplowSearchContext =+ | "basic-actions"+ | "browse"| "command-palette"+ | "data-picker"+ | "dependencies"+ | "document"+ | "embedding-setup"| "entity-picker"+ | "library"+ | "model-migration"| "search-app"- | "search-bar";+ | "search-bar"+ | "type-filter"+ | "other"; // catch-all, kept last rather than alphabetized with the real surfaces-// `SearchContext`s not yet in the snowplow enum; suppressed (emitted as `null`) until the schema catches up.-const PENDING_CONTEXTS = [- "basic-actions",- "browse",- "data-picker",- "dependencies",- "document",- "embedding-setup",- "library",- "model-migration",- "type-filter",-] as const satisfies readonly SearchContext[];+// Frontend contexts not yet in the snowplow enum, emitted as `"other"` until the iglu schema catches up.+const PENDING_CONTEXTS = [] as const satisfies readonly SearchContext[];// Compile-time guard: every `SearchContext` must be in the snowplow enum or in `PENDING_CONTEXTS`.const _allContextsHandled: Exclude<@@ -97,22 +102,20 @@ const _allContextsHandled: Exclude<: "Add the missing SearchContext to the snowplow enum or to PENDING_CONTEXTS" =true;-// Maps a `SearchContext` to its snowplow `context`, or `null` for a pending/absent context (the wire-// schema's `context` is nullable). A `null` result also gates request tracking — see api/search.ts.export const toSnowplowContext = (- context: SearchContext | null | undefined,-): SnowplowSearchContext | null =>- context == null ||+ context: SearchContext,+): SnowplowSearchContext =>(PENDING_CONTEXTS as readonly SearchContext[]).includes(context)- ? null- : (context as SnowplowSearchContext);+ ? "other"+ : // safe: the guard above proves every non-pending context is in the snowplow enum+ (context as SnowplowSearchContext);export type SearchQueryEvent = ValidateEvent<{event: "search_query";search_term_hash: string | null;search_term: string | null;runtime_milliseconds: number;- context: SnowplowSearchContext | null;+ context: SnowplowSearchContext;total_results: number;page_results: number | null;content_type: SearchContentType[] | null;@@ -132,7 +135,7 @@ export type SearchClickEvent = ValidateEvent<{event: "search_click";position: number;target_type: "item" | "view_more";- context: SnowplowSearchContext | null;+ context: SnowplowSearchContext;search_engine: string | null;request_id: string | null;entity_model: string | null;diff --git a/frontend/src/metabase-types/analytics/search.unit.spec.ts b/frontend/src/metabase-types/analytics/search.unit.spec.tsnew file mode 100644index 00000000000..8e75db61687--- /dev/null+++ b/frontend/src/metabase-types/analytics/search.unit.spec.ts@@ -0,0 +1,65 @@+import type { SearchContext } from "metabase-types/api";++import { toSnowplowContentTypes, toSnowplowContext } from "./search";++describe("toSnowplowContentTypes", () => {+ it("returns null when models is null or undefined", () => {+ expect(toSnowplowContentTypes(null)).toBeNull();+ expect(toSnowplowContentTypes(undefined)).toBeNull();+ });++ it("returns an empty array for no models (distinct from a null/absent filter)", () => {+ expect(toSnowplowContentTypes([])).toEqual([]);+ });++ it("passes tracked models through unchanged", () => {+ expect(toSnowplowContentTypes(["card", "dashboard", "dataset"])).toEqual([+ "card",+ "dashboard",+ "dataset",+ ]);+ });++ it("buckets untracked models into 'other'", () => {+ // A model that is a valid SearchModel but not in the snowplow content_type enum.+ expect(toSnowplowContentTypes(["not-a-content-type"])).toEqual(["other"]);+ });++ it("de-duplicates, collapsing repeats and multiple untracked models to a single 'other'", () => {+ expect(+ toSnowplowContentTypes(["card", "card", "mystery-a", "mystery-b"]),+ ).toEqual(["card", "other"]);+ });+});++describe("toSnowplowContext", () => {+ it("passes a snowplow-enum context through unchanged", () => {+ expect(toSnowplowContext("search-app")).toBe("search-app");+ expect(toSnowplowContext("data-picker")).toBe("data-picker");+ });++ it("maps every SearchContext to itself — none is currently bucketed to 'other'", () => {+ // PENDING_CONTEXTS is empty today, so identity holds for all contexts; if a context is later+ // added to PENDING_CONTEXTS it will map to "other" and this assertion should move to expect that.+ // Record<SearchContext, true> forces this list to stay exhaustive: adding a+ // SearchContext member without extending it fails to compile.+ const allContexts: Record<SearchContext, true> = {+ "basic-actions": true,+ browse: true,+ "command-palette": true,+ "data-picker": true,+ dependencies: true,+ document: true,+ "embedding-setup": true,+ "entity-picker": true,+ library: true,+ "model-migration": true,+ "search-app": true,+ "search-bar": true,+ "type-filter": true,+ };+ for (const context of Object.keys(allContexts) as SearchContext[]) {+ expect(toSnowplowContext(context)).toBe(context);+ }+ });+});diff --git a/frontend/src/metabase/analytics/event.ts b/frontend/src/metabase/analytics/event.tsindex 1401fd74954..88baa6ca91a 100644--- a/frontend/src/metabase/analytics/event.ts+++ b/frontend/src/metabase/analytics/event.ts@@ -25,7 +25,7 @@ const VERSIONS: Record<SchemaType, SchemaVersion> = {invite: "1-0-1",model: "1-0-0",question: "1-0-6",- search: "1-1-3",+ search: "1-1-4",serialization: "1-0-1",settings: "1-0-2",setup: "1-0-3",diff --git a/frontend/src/metabase/api/analytics.ts b/frontend/src/metabase/api/analytics.tsindex 55b7c637b6d..874aacb91bb 100644--- a/frontend/src/metabase/api/analytics.ts+++ b/frontend/src/metabase/api/analytics.ts@@ -1,3 +1,5 @@+import _ from "underscore";+import { trackSchemaEvent } from "metabase/analytics";import { hashSearchTerm, shouldReportSearchTerm } from "metabase/common/search";import { openSaveDialog } from "metabase/utils/dom";@@ -69,7 +71,7 @@ type SearchRequestFilter = Pick<| "offset">;-export const trackSearchRequest = (+const trackSearchRequest = (searchRequest: SearchRequestFilter,searchResponse: SearchResponse,duration: number,@@ -102,3 +104,63 @@ export const trackSearchRequest = (};dispatchTrackSearchQuery();};++// The document typeahead has no request-level debounce (it searches per keystroke), unlike every+// other search surface, so its analytics settle here instead.+const DOCUMENT_SEARCH_TRACK_DEBOUNCE_MS = 300;++let latestDocumentSearchRequestId: string | null = null;++const trackSettledDocumentSearch = _.debounce(+ (+ ...[args, data, duration, requestId]: Parameters<typeof trackSearchRequest>+ ) => {+ // Re-checked at fire time: a newer request may have started while this event sat queued.+ if (latestDocumentSearchRequestId === requestId) {+ trackSearchRequest(args, data, duration, requestId);+ }+ },+ DOCUMENT_SEARCH_TRACK_DEBOUNCE_MS,+);++/**+ * Record that a search request started, before any response arrives.+ * Call it for every request so newer document searches supersede pending analytics for older ones.+ */+export const registerSearchStarted = (+ args: SearchRequest,+ requestId: string,+) => {+ if (args.context === "document") {+ latestDocumentSearchRequestId = requestId;+ }+};++/**+ * Publish the search_query event for a fulfilled search request.+ *+ * Query-less requests are not tracked; they are filter/available-model lookups and existence+ * probes, not searches the user performed.+ * Document-context events are debounced to one per settled query, where "settled" is approximate:+ * two document searches fulfilling within the debounce window collapse into the later one; a query+ * re-settled from cache emits nothing new; an abandoned query's late response may still emit while+ * a superseded query whose successor never fulfills emits nothing; and a pending event is lost if+ * the page unloads within the window.+ */+export const trackFulfilledSearch = (+ args: SearchRequest,+ data: SearchResponse,+ duration: number,+ requestId: string,+) => {+ if (!args.q?.trim()) {+ return;+ }++ if (args.context !== "document") {+ trackSearchRequest(args, data, duration, requestId);+ } else if (latestDocumentSearchRequestId === requestId) {+ // Checked at schedule time too, so a stale out-of-order response can't overwrite the queued args.+ trackSettledDocumentSearch(args, data, duration, requestId);+ }+};diff --git a/frontend/src/metabase/api/analytics.unit.spec.ts b/frontend/src/metabase/api/analytics.unit.spec.tsnew file mode 100644index 00000000000..0f39a2394ae--- /dev/null+++ b/frontend/src/metabase/api/analytics.unit.spec.ts@@ -0,0 +1,149 @@+import type { SearchRequest, SearchResponse } from "metabase-types/api";+import { createMockSearchResults } from "metabase-types/api/mocks";++import { registerSearchStarted, trackFulfilledSearch } from "./analytics";++jest.mock("metabase/analytics", () => ({+ trackSchemaEvent: jest.fn(),+ trackSimpleEvent: jest.fn(),+}));++// Reached through requireMock rather than a top-level import: the analytics-import lint rule forbids+// importing `trackSchemaEvent` outside analytics files.+const { trackSchemaEvent: mockTrackSchemaEvent } = jest.requireMock<{+ trackSchemaEvent: jest.Mock;+}>("metabase/analytics");++// Avoid crypto.subtle / Settings in the hashing path; we only care about the tracking lifecycle here.+jest.mock("metabase/common/search/term", () => ({+ hashSearchTerm: jest.fn(async () => "hashed"),+ shouldReportSearchTerm: jest.fn(() => false),+}));++// Real timers, not fake ones: underscore's `_.debounce` binds `Date.now` at import, before jest could+// install fake timers, so `advanceTimersByTime` never moves the clock it reads. Wait past the 300ms+// window (see DOCUMENT_SEARCH_TRACK_DEBOUNCE_MS in analytics.ts) instead.+const SETTLE_WAIT_MS = 350;++const makeRequest = (+ overrides: Partial<SearchRequest> = {},+): SearchRequest => ({+ q: "orders",+ context: "search-bar",+ ...overrides,+});++const makeResponse = (): SearchResponse => createMockSearchResults();++const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));++// trackSearchRequest awaits hashSearchTerm before it fires, so let the microtask queue drain.+const flushMicrotasks = async () => {+ for (let i = 0; i < 5; i++) {+ await Promise.resolve();+ }+};++describe("trackFulfilledSearch", () => {+ afterEach(async () => {+ // Let any queued debounce settle so it can't fire into the next test, then reset call counts.+ await wait(SETTLE_WAIT_MS);+ jest.clearAllMocks();+ });++ it("tracks a non-document search immediately", async () => {+ trackFulfilledSearch(makeRequest(), makeResponse(), 10, "req-1");++ await flushMicrotasks();++ expect(mockTrackSchemaEvent).toHaveBeenCalledTimes(1);+ });++ it("skips a query-less request (whitespace or absent)", async () => {+ trackFulfilledSearch(+ makeRequest({ q: " " }),+ makeResponse(),+ 10,+ "req-1",+ );+ trackFulfilledSearch(+ makeRequest({ q: undefined }),+ makeResponse(),+ 10,+ "req-2",+ );++ await flushMicrotasks();++ expect(mockTrackSchemaEvent).not.toHaveBeenCalled();+ });++ it("debounces a document search until the settle window elapses", async () => {+ const request = makeRequest({ context: "document" });+ registerSearchStarted(request, "req-1");+ trackFulfilledSearch(request, makeResponse(), 10, "req-1");++ await flushMicrotasks();+ expect(mockTrackSchemaEvent).not.toHaveBeenCalled();++ await wait(SETTLE_WAIT_MS);+ await flushMicrotasks();+ expect(mockTrackSchemaEvent).toHaveBeenCalledTimes(1);+ });++ it("collapses multiple document searches within the window into one event", async () => {+ const request = makeRequest({ context: "document" });++ registerSearchStarted(request, "req-1");+ trackFulfilledSearch(request, makeResponse(), 10, "req-1");++ await wait(100);++ registerSearchStarted(request, "req-2");+ trackFulfilledSearch(request, makeResponse(), 10, "req-2");++ await wait(SETTLE_WAIT_MS);+ await flushMicrotasks();++ expect(mockTrackSchemaEvent).toHaveBeenCalledTimes(1);+ });++ it("ignores a stale response without dropping the latest queued event (schedule-time guard)", async () => {+ const request = makeRequest({ context: "document" });++ // The latest request req-2 fulfills and queues its event.+ registerSearchStarted(request, "req-2");+ trackFulfilledSearch(request, makeResponse(), 10, "req-2");++ // A stale older response arrives before the debounce fires. The schedule-time guard must drop it+ // so it can't overwrite the queued req-2 args — otherwise the fire-time guard would then suppress+ // the overwritten event and lose the legitimate req-2 one entirely.+ trackFulfilledSearch(request, makeResponse(), 10, "req-1");++ await wait(SETTLE_WAIT_MS);+ await flushMicrotasks();++ expect(mockTrackSchemaEvent).toHaveBeenCalledTimes(1);+ expect(mockTrackSchemaEvent).toHaveBeenCalledWith(+ "search",+ expect.objectContaining({ request_id: "req-2" }),+ );+ });++ it("suppresses a queued event when a newer document request starts before it fires (fire-time guard)", async () => {+ const request = makeRequest({ context: "document" });++ registerSearchStarted(request, "req-1");+ trackFulfilledSearch(request, makeResponse(), 10, "req-1");++ // A newer request starts inside the debounce window but never fulfills; the queued req-1 event+ // must be dropped at fire time even though it passed the schedule-time check.+ await wait(100);+ registerSearchStarted(request, "req-2");++ await wait(SETTLE_WAIT_MS);+ await flushMicrotasks();++ expect(mockTrackSchemaEvent).not.toHaveBeenCalled();+ });+});diff --git a/frontend/src/metabase/api/search.ts b/frontend/src/metabase/api/search.tsindex 37318982c5c..e172c4a343a 100644--- a/frontend/src/metabase/api/search.ts+++ b/frontend/src/metabase/api/search.ts@@ -1,7 +1,6 @@-import { toSnowplowContext } from "metabase-types/analytics";import type { SearchRequest, SearchResponse } from "metabase-types/api";-import { trackSearchRequest } from "./analytics";+import { registerSearchStarted, trackFulfilledSearch } from "./analytics";import { Api } from "./api";import { provideSearchItemListTags } from "./tags";import { handleQueryFulfilled } from "./utils/lifecycle";@@ -17,16 +16,11 @@ export const searchApi = Api.injectEndpoints({providesTags: (response, error, { models }) =>provideSearchItemListTags(response?.data ?? [], models),onQueryStarted: (args, { queryFulfilled, requestId }) => {- // Only track searches from a surface already in the snowplow schema, with an actual text query.- // Pending contexts (toSnowplowContext → null) stay unpublished until the schema is widened; so do- // query-less requests (filter/available-model lookups, existence probes), which aren't searches.- if (toSnowplowContext(args.context) != null && args.q?.trim()) {- const start = Date.now();- return handleQueryFulfilled(queryFulfilled, (data) => {- const duration = Date.now() - start;- trackSearchRequest(args, data, duration, requestId);- });- }+ registerSearchStarted(args, requestId);+ const start = Date.now();+ return handleQueryFulfilled(queryFulfilled, (data) =>+ trackFulfilledSearch(args, data, Date.now() - start, requestId),+ );},}),}),diff --git a/snowplow/iglu-client-embedded/schemas/com.metabase/search/jsonschema/1-1-4 b/snowplow/iglu-client-embedded/schemas/com.metabase/search/jsonschema/1-1-4new file mode 100644index 00000000000..33a52a6fda5--- /dev/null+++ b/snowplow/iglu-client-embedded/schemas/com.metabase/search/jsonschema/1-1-4@@ -0,0 +1,235 @@+{+ "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",+ "description": "Search events",+ "self": {+ "vendor": "com.metabase",+ "name": "search",+ "format": "jsonschema",+ "version": "1-1-4"+ },+ "type": "object",+ "properties": {+ "event": {+ "description": "Event name",+ "type": "string",+ "enum": [+ "search_query",+ "search_click",+ "new_search_query",+ "search_results_filtered"+ ],+ "maxLength": 1024+ },+ "runtime_milliseconds": {+ "description": "Number of milliseconds it took to successfully run the search query",+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0,+ "maximum": 2147483647+ },+ "context": {+ "description": "Source of the search event. Non-null in practice (the frontend sends a value on every request), but kept nullable here to avoid a major (MODEL) version bump, which would fork events into a separate warehouse table. \"other\" buckets frontend contexts not yet added to this enum.",+ "type": [+ "string",+ "null"+ ],+ "enum": [+ "basic-actions",+ "browse",+ "command-palette",+ "data-picker",+ "dependencies",+ "document",+ "embedding-setup",+ "entity-picker",+ "library",+ "model-migration",+ "search-app",+ "search-bar",+ "type-filter",+ "other",+ null+ ],+ "maxLength": 1024+ },+ "total_results": {+ "description": "The total number of results that matched the query",+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0,+ "maximum": 2147483647+ },+ "page_results": {+ "description": "The number of results returned per page",+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0,+ "maximum": 2147483647+ },+ "position": {+ "description": "The position of the result in the list that was clicked. Zero indexed",+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0,+ "maximum": 2147483647+ },+ "target_type": {+ "description": "The type of item in the search list that was clicked.",+ "type": [+ "string",+ "null"+ ],+ "enum": [+ "item",+ "view_more"+ ]+ },+ "content_type": {+ "description": "Filter for entity types (question, database, model, etc.)",+ "type": [+ "array",+ "null"+ ],+ "items": {+ "description": "An entity type (card, question, dashboard, etc.). \"other\" buckets models that aren't tracked content types.",+ "type": "string",+ "enum": [+ "dashboard",+ "card",+ "dataset",+ "segment",+ "measure",+ "metric",+ "collection",+ "database",+ "table",+ "action",+ "indexed-entity",+ "document",+ "transform",+ "other"+ ],+ "maxLength": 1024+ }+ },+ "creator": {+ "description": "Filter for created by a user",+ "type": [+ "boolean",+ "null"+ ]+ },+ "last_editor": {+ "description": "Filter for last edited by a user",+ "type": [+ "boolean",+ "null"+ ]+ },+ "creation_date": {+ "description": "Filter for a time when a user creates an entity",+ "type": [+ "boolean",+ "null"+ ]+ },+ "last_edit_date": {+ "description": "Filter for a time when a user last edited an entity",+ "type": [+ "boolean",+ "null"+ ]+ },+ "verified_items": {+ "description": "Filter for entities that have been marked as verified",+ "type": [+ "boolean",+ "null"+ ]+ },+ "search_native_queries": {+ "description": "Toggles whether search should include SQL and/or native queries",+ "type": [+ "boolean",+ "null"+ ]+ },+ "search_archived": {+ "description": "Toggles whether search should include archived items",+ "type": [+ "boolean",+ "null"+ ]+ },+ "search_engine": {+ "description": "The search engine used to perform the search",+ "type": [+ "string",+ "null"+ ],+ "maxLength": 1024+ },+ "request_id": {+ "description": "The unique request ID for the search request",+ "type": [+ "string",+ "null"+ ],+ "maxLength": 1024+ },+ "offset": {+ "description": "The offset of the search results (for pagination)",+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0,+ "maximum": 2147483647+ },+ "entity_model": {+ "description": "The model type of the clicked entity",+ "type": [+ "string",+ "null"+ ],+ "maxLength": 1024+ },+ "entity_id": {+ "description": "The ID of the clicked entity",+ "type": [+ "integer",+ "null"+ ],+ "minimum": 0,+ "maximum": 2147483647+ },+ "search_term_hash": {+ "description": "A hash of the search term and instance id",+ "type": [+ "string",+ "null"+ ],+ "maxLength": 1024+ },+ "search_term": {+ "description": "The search term as a string (only reported for specific analytics UUIDs)",+ "type": [+ "string",+ "null"+ ],+ "maxLength": 1024+ }+ },+ "required": [+ "event"+ ],+ "additionalProperties": true+}