# Workspace knowledge ## What is workspace knowledge? Your dashboards already describe your data. A chart names the source it reads, the column it adds up and the categories it splits by. Workspace knowledge reads that back out as **metrics**, such as revenue, and **dimensions**, such as segment or order date. The built-in assistant looks a term up there before it answers. It explains a metric the way your own dashboards compute it, and links the charts that already show it. Members see what it learned under **Definitions**, with a page for every metric and every dimension. > What does churn rate mean in this workspace? No model runs to learn knowledge or to look it up. The one place it uses a model is the short summary each entry carries ([What does a summary say?](/docs/chat/knowledge#what-does-a-summary-say)). ## What does the assistant learn from a dashboard? Each chart contributes the measures it draws and the dimensions it splits them by. A metric carries these facts: - its label, and every other label the same metric is drawn under - its unit, such as USD - how it is computed, such as the sum of a column, where the chart says - the connection, tool and table its numbers come from - the dimensions it is split by, with their time grains - the dashboard filters it follows, and the chart types it is drawn as On a SQL connection such as BigQuery, the assistant also reads the query, so it learns the aggregate, the column and the conditions. An argument named like a key, token or password is blanked before the query is kept. A dimension that splits by time is named after the date column it slices, such as `created_at`. The grains its charts group it by, such as month, week or day, are listed under it. So one date column is one dimension however its charts group it. Where nothing says which date a chart slices, its time split joins one dimension named **time**. A column a chart computes but never draws teaches nothing. Text, file and archived widgets contribute nothing either. A dashboard contributes once its edits settle, about 15 minutes after the last change. When dashboards compute one metric in different ways, each way is kept as its own version. The assistant names the version it used rather than averaging them. A chart copied to three dashboards counts once, as one lineage. ## What does it learn from a notebook? A notebook shared with the workspace contributes too, as weaker evidence than a dashboard. A notebook is exploration, and a dashboard is a chart someone decided to keep. The assistant weighs a version only notebooks compute below a dashboard's. Two kinds of cell teach it something. - A Data cell gives the connection, tool and table, and on a SQL connection what the query computes. A Python cell that only calls a connection's tool counts as one. - The Python cell after it teaches only when it is one line that adds up a column, such as `df.groupby('segment')['amount'].sum()`. Anything longer teaches nothing beyond the Data cell. The code in a notebook is never stored or shown. From that one line, knowledge keeps the column and category names and nothing else, and it keeps no values from a notebook. A new notebook is private, so it contributes nothing until its workspace row in the Sharing pane is **Viewer** or **Editor**. Making it private, archiving it or deleting it removes its contribution within about five minutes. A notebook contributes once its edits settle, about 15 minutes after the last change. A notebook's **Context** tab, in its settings, names under each cell what it contributed, linked to the metric's page. ## Which dashboards does it learn from? A dashboard counts only when every member can open it. Its workspace row in the Sharing pane must be **Viewer** or **Editor**, and it must not be archived. A private dashboard, or one shared with named people only, contributes nothing, so knowledge never tells a member about a board they can't open. Making a dashboard private, archiving it, deleting it or moving it to another workspace removes its contribution within about five minutes. A metric or dimension no dashboard or notebook uses any more is kept as **Archived**, with its notes. It is removed after 90 days unless a note keeps it. An archived note keeps nothing. Guests see none of it, in the app or through an agent. ## Where do you see what it learned? **Definitions** lists every metric and dimension the workspace has learned. Open it from **Settings → Assistant → Definitions**. **Show in sidebar** there adds Definitions to your sidebar in this workspace, for you alone. Each row shows the entry's definition once its summary is written, and its **Type**, Metric or Dimension. A metric's row shows its unit and says **Multiple versions** where dashboards disagree. Every row counts the dashboards and notebooks it is used on, and says when it was first learned and last updated. Search covers names, other labels, definitions and a dimension's values. The app's search (⌘K or Ctrl+K) finds a definition by its name or any other label as well. Three filters narrow the list. 1. **Type** shows only metrics or only dimensions. 2. **Connection** shows the metrics drawn from one connection, and the dimensions they are split by there. 3. **Dimension** shows the metrics one dimension splits. Star a metric or a dimension to find it again with the star filter. Your stars are yours alone. Turn on **Include archived** to show entries no dashboard or notebook uses any more. The list updates as dashboards settle. ### A metric's page Open a metric for its page. The assistant links this page when it answers from knowledge. A tile left of the name shows what kind of number it is, such as $ for money, % for a rate or # for a count. The unit sits beside its name. Underneath, the page counts the dashboards and notebooks that draw it, and the definitions they use when they disagree. When a dashboard draws the metric, the page leads with that chart, as the dashboard last published it, under the chart's title and dashboard and over its sources, as on the dashboard. Its dot says how current it is, as a chart's dot does on a dashboard. If the dashboard has no recent rows, the card names the dashboard to refresh. To see how the metric is computed, open the chart with **Expand**, as on a dashboard. It opens the chart's own view, with the source it reads, the arguments each step sends, the rows each step returns and the transform. Back returns to the metric's page. **Refresh**, at the top of the page, runs the chart again the way its own Refresh on the dashboard does, and the chart updates when it finishes. If you aren't connected to the source it reads, it opens the dashboard's connections instead. Opening a page runs nothing by itself. The cards follow, in two columns on a wide screen and one on a phone. A card with nothing to show isn't drawn. | Card | What it shows | |---|---| | **Description** | What the metric means here, how it is computed, its caveats, and the question the assistant asks when a request doesn't say which version. Each answer jumps to the dashboard or notebook that computes that version, in Evidence. The line under it says it was generated automatically and when, or that the dashboards have changed since | | **Dimensions** | The dimensions it is split by, one line each — its time grains on this metric's charts, or its most common values. A dimension opens its own page | | **Evidence** | Each dashboard and notebook that draws it, how it computes the metric there (such as Sum of amount), how it draws and splits it, how many of its charts or cells, and when it last changed. The line along the bottom names the dashboard and chart where the definition most dashboards use was first seen | | **Top users** | Up to six members who know it best, the people who built the dashboards and notebooks that draw it and who wrote its notes, most first, each saying what they did | ### A dimension's page Open a dimension for its page, laid out like a metric's. The assistant links this page too. The tile left of the name shows the dimension's kind, such as a calendar for time or a globe for a place. Underneath, it says how many dashboards and notebooks use it. When a chart already splits a metric by this dimension, the page leads with that chart, as the dashboard last published it. It prefers a bar chart, then a pie, and a line for a time dimension. A dimension no chart splits by has no chart. **Expand** on the chart opens it as on a dashboard, where the column it is read from shows in the chart's source and arguments. | Card | What it shows | |---|---| | **Description** | What the dimension means here, where its values come from, and its caveats. The line under it says it was generated automatically and when, or that the dashboards have changed since | | **Metrics** | The metrics it splits, one line each — the time grains each is drawn at, or how many lineages and dashboards split it. A metric opens its own page | | **Evidence** | Each dashboard and notebook that uses it, the metrics it splits there, how many charts, and when it last changed. The line along the bottom names the dashboard and chart where it was first seen | | **Values** | A time dimension's grains, or its most common values, each with its row count and links to up to three dashboards or notebooks that show it. **Values off** means the workspace's **Capture dimension values** switch is off | | **Top users** | Up to six members who know it best, the people who built the dashboards and notebooks that use it and who wrote its notes, most first | ### Notes on a page **Notes**, at the top of a metric's or a dimension's page, opens its notes beside it. On a phone, Notes is in the bar along the bottom. The menu at the top of the page has **Copy link**, the page's own address, and **History**. A connection's menu in **Settings → Connections** has a **Definitions** item. It opens the list filtered to the metrics drawn from that connection and the dimensions they are split by. ### History of a definition **History**, in the menu at the top of a page, opens the page's settings on the saved versions of a metric's or a dimension's definition, newest first. A version is every definition the entry has at one moment. One is saved when a dashboard or notebook settles and a definition appears, changes or stops being drawn. Moving a date range saves nothing, since the definition is the same. Each row says what changed, such as "A definition appeared on Finance", and when. Click a version to open it. It lists everything that changed, and below that shows each definition as it was at that version, with how it was computed, the connection and tool it read, and the arguments its chart sent. Click it again to close it. History has no restore, because a definition comes from your dashboards. **Open board history** on a version opens the history of the dashboard or notebook that changed it. Restore that, and the definition follows once the dashboard settles. ### Ask the assistant from a definition **Ask**, beside Notes at the top of a metric's or a dimension's page, opens the built-in assistant on that entry. Each chat starts with the entry's evidence already loaded, the same answer the assistant gets when it looks the entry up, so it answers from your dashboards without searching first. It can look deeper, compare the dashboards that disagree, and save a note when you ask it to record what you know, asking before it does. It can't change a definition, since a definition comes from your dashboards. A chat keeps the evidence it started with. When the dashboards change during a chat, the assistant looks the entry up again before it answers. Each chat is listed under **Chats** with the entry as its source, and its usage counts as chat usage. Guests don't get it. ## What does a summary say? Each entry carries a short summary, written by a model from the entry's evidence and its notes. It has four parts. - A definition, one sentence on what the entry means in this workspace. - How it is computed, naming the sources each version reads. - Caveats, such as where versions disagree or what a note warns about. - On a metric with more than one version, the question the assistant asks when a request doesn't say which, with one answer for each version. A summary never carries a figure, a count or a recommendation. Figures change with every refresh, and a recommendation belongs in a note. The assistant weighs a note above the summary. A summary is rewritten only when the evidence behind it changes, never when a dashboard refreshes. Until the rewrite, the entry's page says the dashboards have changed and still shows the earlier summary. When a dashboard leaves knowledge, the summaries it fed are cleared until they are rewritten without it. Writing summaries is the one place workspace knowledge uses a model. Its usage is recorded for the workspace as background upkeep, the way a dashboard's context is. At most 20 summaries are written in a workspace in any 15 minutes, and the rest wait their turn. ## How do you add a note? A note records what the dashboards can't say, such as which version to trust for anything external, or what a segment's letters stand for. Any admin or member can write one in the **Notes** of a metric's page or a dimension's page. A note is about one metric or one dimension. Each note shows its author's name and the date, and the assistant also reads the author's role. The assistant weighs a note against what the dashboards show and never follows it as an instruction. A rule every answer should follow belongs in **Workspace instructions**, under Settings → Assistant, instead. You can also ask the built-in assistant to save a note, and it asks before it does. > Note that finance.revenue is the figure for anything external, because Stripe reports gross Type **@** in a note to mention a person, dashboard or notebook, or **/** for a skill. The mention links to it, and nobody is notified. The author can edit a note from its menu. An edited note is marked **edited**, and the entry's summary is rewritten with the new words. A workspace admin can archive anyone's note but edit only their own. The author or a workspace admin can archive a note. An archived note leaves every answer and summary and stops counting toward the limits. The menu at the top of **Notes** switches between **Active**, **Archived** and **All**. Archived notes offer **Restore** and **Delete**, and only an archived note can be deleted. A metric or dimension keeps up to 200 archived notes, and past that, archiving one more deletes the oldest of the rest. ## What happens to a note from your agent? Your agent, meaning your own MCP client such as Claude Code or Codex, gets the same three lookup tools the built-in assistant uses. It can save a note too ([Workspace knowledge tools](/docs/mcp-tools/knowledge)). A note from your agent is live as soon as it is saved. It is signed with your name like any other, and marked **From an agent** in the entry's notes. The assistant and every agent weigh it against what the dashboards show and never follow it as an instruction. If it's wrong, archive it. ## When does knowledge keep values from your data? Dimension values are the one place knowledge holds data from your sources. For each dimension it keeps the most common values in the rows its charts had published when knowledge last read the dashboard, such as segment names or regions. That lets the assistant answer "tell me about segment A" by finding the charts that carry A. Dates are never kept as values, since a time dimension lists its grains instead. One switch named **Capture dimension values**, in Settings → Assistant → Definitions, covers the whole workspace. It is on by default, and only admins see it. Turned off, it stops new values being kept, and the values already kept are removed within minutes. Metrics, dimensions, versions and notes stay. ## How much can knowledge hold? | | Limit | |---|---| | Metrics in a workspace | 500 | | Dimensions in a workspace | 300 | | Values kept from one chart | The 20 most common for each dimension | | One note | 1,000 characters | | Notes on one metric or dimension | 100, and 50 of them can be yours. Archived notes don't count | | Archived notes on one metric or dimension | 200, then the oldest is deleted | | Saved versions of one metric or dimension | 50, then the oldest is deleted | | What one note can be about | One metric or one dimension | | Notes saved | 20 per person per minute | | Summaries written | 20 per workspace per 15 minutes | At the metric or dimension limit, new labels stop being added and Settings → Assistant → Definitions says so. Metrics and dimensions already learned keep updating.