Configure Metabot context

The metadata, content, and settings that change what Metabot can find and how it uses it.

Metabot answers questions using the metadata and content in your Metabase. This page lists what you can change to improve its answers, and what each change does.

What Metabot searches depends on where people use it

Metabot can only see what the person asking has permission to see.

Where	What Metabot searches
Chat sidebar	Tables, models, metrics, measures, segments, questions, dashboards, and documents the person has permission to see, plus their recently viewed items.
AI exploration	The Library, if you have one. Otherwise, the collection for natural language querying.
SQL generation	Tables in the database selected in the SQL editor.
Documents (Ask Metabot)	Models and metrics in the collection for natural language querying, or all models and metrics if you haven’t set one. To write SQL, the database the person @-mentions.

Metabot also sees the item the person has open, any items they @-mention, and your glossary.

In documents, Ask Metabot can only build a chart, so Metabot doesn’t search tables, questions, or dashboards, and it ignores recently viewed items. Metabot prefers an existing model or metric, and only writes SQL if none fits or when directly asked for SQL. To write SQL, @-mention exactly one database.

Add descriptions to tables, columns, models, and metrics

Metabot can read item descriptions (including when searching for stuff). In your descriptions:

• Say what the item means to your business and which questions it answers.
• Explain columns that are easy to misread: codes, flags, anything called status, and anything with an internal encoding. (Metabot already knows the column types, though).
• Include the names people use for the item outside your database. Metabot can’t know these on its own.

For example, here’s a useful description for an ID column:

Unique ID for the product. Customer-facing emails and screens call this the "Invoice number" or "Confirmation number".

You can ask Metabot to draft descriptions, but be careful with this; Metabot only knows what’s in your database. It can’t know that this ID is called the “Invoice number” in your app, which is exactly the kind of context worth writing down.

Admins and data analysts can edit table and column descriptions in Data Studio. To add descriptions to a model’s columns, see Add metadata to columns in a model.

Define company terms in the glossary

Add acronyms, product names, and terms with a company-specific meaning to the glossary in Data Studio > Glossary.

• Metabot gets the glossary with every message, in every place people use Metabot.
• Metabot only gets the 100 most recently updated terms.
• Keep definitions short, since they’re sent with every message.

For example, if you define “active customer” as “logged in during a quarter”, Metabot knows what people mean when they ask “How many active customers did we have over the last four quarters?”

Mark foreign keys so Metabot can join tables

When a column’s semantic type is Foreign Key and points to a column in another table, Metabot sees which table and column it links to. Without that, Metabot sees a column like customer_id with no hint that it joins anywhere, and may look for customer fields in the wrong table.

Metabase picks up foreign keys that your database defines as constraints. Many databases don’t define them, so check the columns people join on most. Metabot doesn’t see other semantic types, like Creation date or Category.

Define measures and segments for calculations people get wrong

If people calculate “net revenue” or filter for “active customers” in slightly different ways, define the calculation once as a measure or segment on the table.

When Metabot looks at a table, it sees the table’s measures and segments and is instructed to use them instead of writing its own calculation. Metabot also searches for measures and segments by name, especially when a question names a rate (“churn rate”) or a group (“active customers”).

Curate the sources you want Metabot to use

When more than one source could answer a question, Metabot picks the most curated one: Metrics** are preferred for calculations. Models** serve as a fallback when no matching metric is found. Build a metric if you want Metabot to reuse a calculation.

Metabot will respond with an existing question if it directly answers the question. Tables rank higher if they’re published or their visibility layer is Final rather than Internal. Verified items and items in official collections also count as endorsed.

Old and abandoned content also competes in Metabot’s search results. To find items to clean up, check the Content with cobwebs dashboard in Usage analytics and Content diagnostics in Monitor. Then clear out unused items from your collections.

Hide tables and columns nobody should query

• Tables: In Data Studio > Connected data, set the table’s visibility layer to Hidden. Hidden tables don’t show up in Metabot’s search or in the tables it considers for SQL, and Metabot can’t build query-builder questions on them. Hidden tables also disappear from the query builder and stop syncing.
• Columns: Set the column’s visibility to Do not include. Metabot never sees these columns. They also disappear from the query builder.

Neither setting is a permission: people can still query hidden tables and columns with SQL. To control what data Metabot view and query, use data permissions.

Show Metabot real values for columns people filter on

Metabot can only look up a column’s values if the column’s Filtering setting is A list of all values. With Search box or Plain input box, Metabot only gets summary statistics, so it has to guess what values like churned or EMEA look like in your data.

Use A list of all values for columns that people filter on by name, like statuses, categories, and region codes. This setting also changes the filter widget people see.

Restrict Metabot to curated content

In Admin > AI, on the Internal tab, turn on Only use verified or curated content. Metabot’s search results, recently viewed items, suggested prompts, and the models and metrics Ask Metabot uses in documents then only include content that’s:

• Verified.
• In an official collection.
• Published to the Library. Published tables only count if their visibility layer is Final.

Turn this on only once you’ve curated enough content. If nothing qualifies, Metabot’s searches come back empty. See Verified or curated content.

Publish tables and metrics to the Library

If your Metabase has a Library, AI exploration searches it first, matching questions against each item’s name and description.

• Publish tables in Data Studio > Semantic layer.
• Move metrics into the Library > Metrics collection.
• Add descriptions to everything you publish.

The Library only holds tables, metrics, dashboards, and SQL snippets.

AI exploration can still look at tables outside the Library, but it starts with what’s in the Library. If nothing in the Library matches a question well, Metabot may ask the person to clarify instead of guessing.

Without a Library, point AI exploration at a collection

In Admin > AI, on the Internal tab, set Collection for natural language querying to a collection with your best models and metrics. AI exploration then only searches that collection and its subcollections. Ask Metabot in documents also only picks models and metrics from that collection, whether or not you have a Library. People can still @-mention items outside it. See Collection for natural language querying.

Use system prompts for conventions, not facts

In Admin > AI > System prompts, you can write separate instructions for AI chat, Natural language queries, and SQL generation. Metabot gets the matching prompt with every message. Ask Metabot in documents doesn’t use any of these prompts.

• Good for: tone, formatting, and conventions that always apply, like “Our fiscal year starts on February 1.”
• Not for: facts about specific tables or columns. Put those in descriptions, which Metabot only reads when it uses that item.

Keep system prompts short. See AI system prompts.

Open the item before asking about it

When a table, model, or question is open, Metabot sees its columns and their descriptions, its measures and segments, and the tables it joins to. Opening the right item first is the most direct way to point Metabot at the right data.

In the chat sidebar, Metabot also sees recently viewed items, so viewing a relevant table or question first helps. AI exploration and Ask Metabot in documents ignore recently viewed items.

Documents are an exception to this: when a document is open, the chat sidebar doesn’t see what’s in it. Metabot can still find a document by searching for it, so mention the document’s name in your question if needed.

Some changes don’t affect Metabot

• Table display names: Metabot works with a table’s database name, not its display name. Search does match display names, though, so a good display name still helps Metabot find the table. Column display names do reach Metabot.
• Why this table is interesting and Things to be aware of about this table in Data Reference: Metabot never sees these, put that information in the description instead.
• Verification doesn’t add content to the Library. Verified items count as curated content, but only publishing or moving an item puts it in the Library.