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
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.selmerindex 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", "bOnly 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 extraDo 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.selmerindex 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 inYou 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 itdiff --git a/resources/metabot/prompts/shared/prompt_snippets/grounding.selmer b/resources/metabot/prompts/shared/prompt_snippets/grounding.selmerindex 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. EveNever 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.mdindex 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 mistakesShape rules: