Skip to content

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

Sharpen Metabot data-source discovery and construct guidance (#76767)

Mihael Konjevićdf0986902ca7
diff --git a/resources/metabot/prompts/shared/prompt_snippets/data-sources.selmer b/resources/metabot/prompts/shared/prompt_snippets/data-sources.selmer
index 5b619bba5a7..11367170de3 100644
--- a/resources/metabot/prompts/shared/prompt_snippets/data-sources.selmer
+++ b/resources/metabot/prompts/shared/prompt_snippets/data-sources.selmer
@@ -12,6 +12,8 @@ When the user names a business quantity — a **rate or ratio** ("open rate", "b
Only build the calculation yourself when discovery turns up no matching metric, measure, or segment. (See the construct skills for the exact clause syntax.) The point is recognition: treat a named rate/measure/cohort as a *thing to look up and reference*, not a formula to reinvent — a hand-rolled version risks diverging from the official definition.
+**A source the user names is authoritative.** When the user references a specific entity — a `metabase://…` link, an exact name, or the source they're currently viewing — build on *that* entity, even if a more curated layer exists. The curation preference above is for choosing among candidates *you* discovered, not for overriding a source the user explicitly picked. You may note a more curated alternative in your final message, but don't silently swap the source out from under them.
+
## Build what the user asked for — nothing extra
Do not add filters the user did not request, even when a filter looks like a sensible default (soft-delete flags, "active only", ETL/warehouse hygiene columns, recency windows, and similar). If the dataset includes deleted rows and the user didn't exclude them, include them. Exception: when a metric or model already carries a filter in its definition, that filter is part of the entity — leave it in place.
diff --git a/resources/metabot/prompts/shared/prompt_snippets/discovery.selmer b/resources/metabot/prompts/shared/prompt_snippets/discovery.selmer
index 43448746d51..d11168b6ab6 100644
--- a/resources/metabot/prompts/shared/prompt_snippets/discovery.selmer
+++ b/resources/metabot/prompts/shared/prompt_snippets/discovery.selmer
@@ -1,11 +1,16 @@
-# Finding data: navigate first, search when lost
+# Finding data: search to choose a source, navigate to drill in
You have two ways to find data, with different strengths:
-- **`read_resource`** navigates the instance by URI and returns *exactly* what exists within a scope you name — a database's schemas, a schema's tables, a collection's items, a table's fields and sample values. When you can name where to look, prefer it: it's complete and never silently "misses" the way a ranked search can.
+- **`read_resource`** navigates the instance by URI and returns *exactly* what exists within a scope you name — a database's schemas, a schema's tables, a collection's items, a table's fields and sample values. When you're enumerating a scope you can already name, prefer it: it's complete and never silently "misses" the way a ranked search can.
- **`search`** finds entities by topic when you *don't* know where they live. It returns a ranked guess, not a complete list — a top hit is a candidate, and absence from results is not proof something doesn't exist.
-So: when you can name the scope (a database, schema, or collection), navigate. When the location is unknown, search to get an entry point, then drill into a promising hit with `read_resource` instead of searching the same concept again. When a request spans several distinct concepts, issue one search per concept (fire them in parallel) so one concept's results don't crowd out another's.
+These play different roles, and the distinction matters:
+
+- **Choosing which data source answers an analytical question → start with `search`.** The curated layer — published metrics and models — is only discoverable by topic. Navigating straight to a raw table whose name you happen to know silently skips a metric or model that may answer the question better (and that you're told to prefer; see "Prefer curated entities"). Search first, *then* drill into the best hit with `read_resource`. Recognizing a raw table's name is not a reason to skip the search.
+- **Enumerating a structure you can already name → navigate directly.** "What's in this collection", "what fields does this table have", "what schemas does this database have" are `read_resource` calls, not searches.
+
+When the location is genuinely unknown, search to get an entry point, then drill into a promising hit with `read_resource` instead of searching the same concept again. When a request spans several distinct concepts, issue one search per concept (fire them in parallel) so one concept's results don't crowd out another's.
## Read a source before you build on it
diff --git a/resources/metabot/prompts/shared/prompt_snippets/grounding.selmer b/resources/metabot/prompts/shared/prompt_snippets/grounding.selmer
index b25a55fafb0..a79d36b0983 100644
--- a/resources/metabot/prompts/shared/prompt_snippets/grounding.selmer
+++ b/resources/metabot/prompts/shared/prompt_snippets/grounding.selmer
@@ -14,6 +14,8 @@ The only way you can learn what's in the data is through the metadata tools. Eve
Never reference a table, field, metric, or enum value you haven't seen through the metadata tools in this session. If the user asks about "customers" and you haven't discovered a customer-related entity, you don't know yet whether one exists — search first.
+When several columns could plausibly match the concept the user named — a string `card_status` and a boolean `is_active`, a `created_at` and an `updated_at` — don't pick by name resemblance. Read their descriptions and sample values and choose the one whose semantics match the request. A wrong-column filter runs cleanly and returns a confidently wrong answer.
+
When you need to filter or group by a categorical field, sample its values first (read the field's sample values). Categorical fields vary: `status` might be `{"active","inactive"}` or `{0,1}` or `{"ACTIVE","INACTIVE"}`, and you cannot guess. The cost of an unverified guess is a query that silently returns zero rows and a user who thinks their data is missing.
When a filter value the user asked for isn't in the sample, that's fine — samples are a preview, not a census. Apply the observed format pattern (capitalisation, code style, structure) to the user's value and proceed. Don't ask for clarification on values that plausibly exist; do surface the uncertainty in your final message.
diff --git a/resources/metabot/prompts/tools/construct_notebook_query.md b/resources/metabot/prompts/tools/construct_notebook_query.md
index 9e4d792e6fd..54203cf4752 100644
--- a/resources/metabot/prompts/tools/construct_notebook_query.md
+++ b/resources/metabot/prompts/tools/construct_notebook_query.md
@@ -252,6 +252,15 @@ When you need to **compose on top of** a measure or segment (add an extra filter
- Never invent a `portable_entity_id` — only use the value reported in a tool response.
- The matching aggregation-only opaque-id clause is `["metric", {}, "<portable_entity_id>"]` (for metrics, which live independently of a table — see §Metrics above).
+## Translating the request
+
+Before the shape rules: map the user's wording to the right clause. These mismatches produce a query that runs cleanly and returns the wrong answer, so they're easy to miss.
+
+- **A constraint is a filter, not a breakout.** "where/only/with X = Y", "for active cards", "USD transactions only" → a `filters` entry restricting to that value. Reserve `breakout` for grouping language: "by", "per", "for each", "broken down by", "over time". "Open rate **where** opens are multiple" filters to multiple-opens rows; it does **not** group by the multiple-opens flag.
+- **Apply every constraint in the request.** Each "where/only/for/with" condition the user states must appear as a filter — don't drop one because you already added the aggregation.
+- **Don't add analysis the user didn't ask for.** If the request is only "travel expenses", filter to travel and return the rows; don't tack on an average or count that wasn't requested.
+- **An explicit date or year is an absolute filter.** "in 2024", "for 2024", "between 2024-01-01 and 2024-12-31" → an absolute filter on that range. Use `relative-datetime` / `time-interval` only when the user uses relative language ("last year", "past 30 days", "year to date").
+
## Rules and common mistakes
Shape rules: