Skip to content

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

feat(search): publish analytics for every search context (#75443)

Chris Trutera6da15a4b1e6
diff --git a/frontend/src/metabase-types/analytics/search.ts b/frontend/src/metabase-types/analytics/search.ts
index b433eff5e1b..b578e45e25e 100644
--- a/frontend/src/metabase-types/analytics/search.ts
+++ b/frontend/src/metabase-types/analytics/search.ts
@@ -1,3 +1,5 @@
+import type { SearchContext, SearchModel } from "metabase-types/api";
+
type SearchEventSchema = {
event: string;
runtime_milliseconds?: number | null;
@@ -28,34 +30,89 @@ type ValidateEvent<
Record<Exclude<keyof T, keyof SearchEventSchema>, never>,
> = T;
-// keep in sync with the `search` snowplow schema
-type SearchContentType =
- | "dashboard"
- | "card"
- | "dataset"
- | "segment"
- | "measure"
- | "metric"
- | "collection"
- | "database"
- | "table"
- | "action"
- | "indexed-entity"
- | "document"
- | "transform";
+// The snowplow `search` schema's `content_type` enum; keep in sync with
+// snowplow/iglu-client-embedded/schemas/com.metabase/search/jsonschema/1-1-3
+const SNOWPLOW_CONTENT_TYPES = [
+ "dashboard",
+ "card",
+ "dataset",
+ "segment",
+ "measure",
+ "metric",
+ "collection",
+ "database",
+ "table",
+ "action",
+ "indexed-entity",
+ "document",
+ "transform",
+] as const;
-type SearchContext =
- | "search-app"
- | "search-bar"
+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.
+export const toSnowplowContentTypes = (
+ models: SearchModel[] | null | undefined,
+): SearchContentType[] | null =>
+ models == null
+ ? null
+ : Array.from(new Set(models)).filter((model): model is SearchContentType =>
+ SNOWPLOW_CONTENT_TYPE_SET.has(model),
+ );
+
+// 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.
+type SnowplowSearchContext =
| "command-palette"
- | "entity-picker";
+ | "entity-picker"
+ | "search-app"
+ | "search-bar";
+
+// `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[];
+
+// Compile-time guard: every `SearchContext` must be in the snowplow enum or in `PENDING_CONTEXTS`.
+const _allContextsHandled: Exclude<
+ SearchContext,
+ SnowplowSearchContext | (typeof PENDING_CONTEXTS)[number]
+> extends never
+ ? true
+ : "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 ||
+ (PENDING_CONTEXTS as readonly SearchContext[]).includes(context)
+ ? null
+ : (context as SnowplowSearchContext);
export type SearchQueryEvent = ValidateEvent<{
event: "search_query";
search_term_hash: string | null;
search_term: string | null;
runtime_milliseconds: number;
- context: SearchContext | null;
+ context: SnowplowSearchContext | null;
total_results: number;
page_results: number | null;
content_type: SearchContentType[] | null;
@@ -75,7 +132,7 @@ export type SearchClickEvent = ValidateEvent<{
event: "search_click";
position: number;
target_type: "item" | "view_more";
- context: SearchContext | null;
+ context: SnowplowSearchContext | null;
search_engine: string | null;
request_id: string | null;
entity_model: string | null;
diff --git a/frontend/src/metabase-types/api/search.ts b/frontend/src/metabase-types/api/search.ts
index 0083c0736ed..ced1926fa2a 100644
--- a/frontend/src/metabase-types/api/search.ts
+++ b/frontend/src/metabase-types/api/search.ts
@@ -130,19 +130,19 @@ export type ModelResult = SearchResult<number, "dataset">;
// The frontend surface that issued a search request; the backend uses it to pick ranking weights and
// filter defaults. Keep in sync with `metabase.search.config/ui-contexts`.
export type SearchContext =
- | "search-bar"
- | "search-app"
- | "command-palette"
- | "entity-picker"
- | "data-picker"
- | "type-filter"
| "basic-actions"
| "browse"
- | "embedding-setup"
+ | "command-palette"
+ | "data-picker"
+ | "dependencies"
| "document"
+ | "embedding-setup"
+ | "entity-picker"
| "library"
- | "dependencies"
- | "model-migration";
+ | "model-migration"
+ | "search-app"
+ | "search-bar"
+ | "type-filter";
export type SearchRequest = {
q?: string;
diff --git a/frontend/src/metabase/api/analytics.ts b/frontend/src/metabase/api/analytics.ts
index 56fdb07325b..55b7c637b6d 100644
--- a/frontend/src/metabase/api/analytics.ts
+++ b/frontend/src/metabase/api/analytics.ts
@@ -1,7 +1,10 @@
import { trackSchemaEvent } from "metabase/analytics";
import { hashSearchTerm, shouldReportSearchTerm } from "metabase/common/search";
-import { isTrackedSearchContext } from "metabase/common/search/analytics";
import { openSaveDialog } from "metabase/utils/dom";
+import {
+ toSnowplowContentTypes,
+ toSnowplowContext,
+} from "metabase-types/analytics";
import type { SearchRequest, SearchResponse } from "metabase-types/api";
import { Api } from "./api";
@@ -80,7 +83,7 @@ export const trackSearchRequest = (
: null,
search_term:
shouldReportSearchTerm() && searchRequest.q ? searchRequest.q : null,
- content_type: searchRequest.models ?? null,
+ content_type: toSnowplowContentTypes(searchRequest.models),
creator: !!searchRequest.created_by,
creation_date: !!searchRequest.created_at,
last_edit_date: !!searchRequest.last_edited_at,
@@ -88,9 +91,7 @@ export const trackSearchRequest = (
verified_items: !!searchRequest.verified,
search_native_queries: !!searchRequest.search_native_query,
search_archived: !!searchRequest.archived,
- context: isTrackedSearchContext(searchRequest.context)
- ? searchRequest.context
- : null,
+ context: toSnowplowContext(searchRequest.context),
runtime_milliseconds: duration,
total_results: searchResponse.total,
page_results: searchResponse.limit,
diff --git a/frontend/src/metabase/api/search.ts b/frontend/src/metabase/api/search.ts
index 4bf1b65b50b..37318982c5c 100644
--- a/frontend/src/metabase/api/search.ts
+++ b/frontend/src/metabase/api/search.ts
@@ -1,4 +1,4 @@
-import { isTrackedSearchContext } from "metabase/common/search/analytics";
+import { toSnowplowContext } from "metabase-types/analytics";
import type { SearchRequest, SearchResponse } from "metabase-types/api";
import { trackSearchRequest } from "./analytics";
@@ -17,9 +17,10 @@ export const searchApi = Api.injectEndpoints({
providesTags: (response, error, { models }) =>
provideSearchItemListTags(response?.data ?? [], models),
onQueryStarted: (args, { queryFulfilled, requestId }) => {
- // Only track searches with an actual text query. Query-less requests are filter/available-model
- // lookups and internal existence probes, not searches the user performed.
- if (isTrackedSearchContext(args.context) && args.q?.trim()) {
+ // 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;
diff --git a/frontend/src/metabase/common/search/analytics.ts b/frontend/src/metabase/common/search/analytics.ts
index 3f8c516b723..2133a037665 100644
--- a/frontend/src/metabase/common/search/analytics.ts
+++ b/frontend/src/metabase/common/search/analytics.ts
@@ -1,32 +1,13 @@
import { trackSchemaEvent } from "metabase/analytics";
-import type { SearchContext, SearchRequest } from "metabase-types/api";
+import { toSnowplowContext } from "metabase-types/analytics";
+import type { SearchContext } from "metabase-types/api";
import { hashSearchTerm, shouldReportSearchTerm } from "./term";
-// The search `context` values we publish Snowplow analytics events for.
-// The other contexts (data pickers, browse, etc.) also issue searches; we don't publish those because it
-// would require a Snowplow schema migration — this list must stay a subset of the `context` enum in the
-// iglu `search` schema (snowplow/iglu-client-embedded/schemas/com.metabase/search/jsonschema/*).
-const ANALYTICS_TRACKED_CONTEXTS = [
- "search-app",
- "search-bar",
- "command-palette",
- "entity-picker",
-] as const satisfies readonly SearchContext[];
-
-export type AnalyticsSearchContext =
- (typeof ANALYTICS_TRACKED_CONTEXTS)[number];
-
-export const isTrackedSearchContext = (
- context: SearchContext | null | undefined,
-): context is AnalyticsSearchContext =>
- context != null &&
- (ANALYTICS_TRACKED_CONTEXTS as readonly SearchContext[]).includes(context);
-
type TrackSearchClickParams = {
itemType: "item" | "view_more";
position: number;
- context: SearchRequest["context"];
+ context: SearchContext;
searchEngine: string;
requestId?: string | null;
entityModel?: string | null;
@@ -49,7 +30,7 @@ export const trackSearchClick = ({
event: "search_click",
position,
target_type: itemType,
- context: isTrackedSearchContext(context) ? context : null,
+ context: toSnowplowContext(context),
search_engine: searchEngine,
request_id: requestId,
entity_model: entityModel,
diff --git a/src/metabase/search/config.clj b/src/metabase/search/config.clj
index f0c5f1f90b9..8d03d7db28c 100644
--- a/src/metabase/search/config.clj
+++ b/src/metabase/search/config.clj
@@ -341,19 +341,19 @@
Selects ranking weights ([[static-context-weights]]) and filter defaults ([[filter-defaults-by-context]]).
Keep in sync with the frontend `SearchContext` type (frontend/src/metabase-types/api/search.ts).
Give every value a comment naming the surface that issues it."
- [:search-bar ; the global navbar search typeahead
- :search-app ; the full-page search results app
+ [:basic-actions ; the command palette's basic-actions "do any models exist?" gate (New action), not a user search
+ :browse ; the Browse models / Browse metrics pages
:command-palette ; the ⌘K command palette
- :entity-picker ; the entity-picker modal (cards, dashboards, collections, …)
:data-picker ; picking a data source (table/model/metric) while building a query
- :type-filter ; the search type-filter dropdown's available-models lookup
- :basic-actions ; the command palette's basic-actions "do any models exist?" gate (New action), not a user search
- :browse ; the Browse models / Browse metrics pages
- :embedding-setup ; embedding/SDK setup and preview resource selection
+ :dependencies ; the dependency-graph entry search (EE)
:document ; entity references embedded in documents
+ :embedding-setup ; embedding/SDK setup and preview resource selection
+ :entity-picker ; the entity-picker modal (cards, dashboards, collections, …)
:library ; the data-studio Library page (EE)
- :dependencies ; the dependency-graph entry search (EE)
- :model-migration]) ; the migrate-models admin page (EE)
+ :model-migration ; the migrate-models admin page (EE)
+ :search-app ; the full-page search results app
+ :search-bar ; the global navbar search typeahead
+ :type-filter]) ; the search type-filter dropdown's available-models lookup
(def ^:private non-ui-contexts
"Search `context` values for non-frontend callers.