Back to the index · Previous: Agent Studio
How it works#
A space gives Sarah one topic to answer about, set up by the person who knows it best. Asked in a space, Sarah's answers are more accurate because she is told exactly where to look and how your business counts things.
A space holds:
- Tables: the few Gold and Silver tables for the topic, written
layer.table(for examplegold.dbt_retail_daily_store_sales). Sarah reads only these in the space. - Instructions: free text in your own words. "A week runs Monday to Sunday. Leave out closed stores. Sales are in USD."
- Business terms: a word, what it means, and its SQL when there is one. revenue =
SUM(net_sales), the fiscal year start, the key two tables join on. - Starter questions: shown on the Sarah page when the space is chosen.
- Sharing: a person, a group, or everyone in the workspace may ask in it.
Four rules hold in every space:
- Sarah runs as the person who asks. Their grants, row filters and column masks apply. A space only narrows what Sarah may read; sharing a space never shares access to data.
- Only the space's tables. Every query is checked before it runs; a table outside the space is refused.
- Only the space's instructions and terms. Sarah's prompt holds the space, nothing else.
- Without a space, Sarah works as before: all of Gold, with the approved Semantics definitions.
Create a space#
- Left rail → ML & AI → Spaces → New.
- Give it a name and say what it answers (Retail store sales: daily sales, units and margin per store).
- Tick its tables. Keep it to one topic; a space holds up to 25 tables.
- Write the instructions and add the business terms.
- Add a few starter questions and press Create space.
The owner (you, unless you change it) and admins change the space; people it is shared with ask in it.
Ask in a space#
On the Sarah page, choose the space in Ask in above the question box (All of Gold is Sarah without a space). The starter questions appear; ask as usual. Each answer shows Space: name.
Under an answer given in a space:
- 👍 / 👎: a thumbs-down asks what is wrong and sends the answer to the space owner's Fix queue.
- Save as trusted (the owner only): keeps this question, its SQL and its dashboard as a trusted answer.
- cost: what the model tokens of this answer cost.
Deep answer#
Tick Deep answer for a question that needs more than one look at the data ("why did store sales fall last week?"). Sarah plans, runs one query per step, reads each result, decides the next step, and writes a short report. Each finding names the steps it rests on, and each step opens to show its SQL.
A deep answer stops at 4 steps (at most 6) and 30,000 tokens; when either runs out, Sarah writes the report from what she has and says so (stopped at the step limit). The cost is shown on the answer.
Trusted answers#
A trusted answer is a question with the SQL that answers it right. When someone asks the same thing in the space, Sarah runs that SQL (as them) instead of writing new SQL, and the answer carries a Trusted badge.
- Save one: from any of your answers in the space, press Save as trusted. Or, on the space's Trusted answers tab, Add by hand with a question and SQL.
- Same question? Sarah compares the new question with the saved ones by meaning: by embedding similarity when the server has an embeddings key, otherwise the model decides among the closest few. Other dates or values count as the same question; another measure, breakdown or filter does not.
- Parameters: write
{{start_date}}in the SQL where a value goes (no quotes) and declare it (date, number or text, with a default). Sarah fills it from the question ("since October 1" givesDATE '2026-10-01') or uses the default. A value is always turned into a plain date, number or quoted text; it can never add SQL.
SELECT store_id, CAST(SUM(net_sales) AS DOUBLE) AS net_sales
FROM datasimple.gold.dbt_retail_daily_store_sales
WHERE sales_date >= {{start_date}}
GROUP BY store_id
ORDER BY net_sales DESC
If a trusted answer cannot run (a parameter without a value, a column that changed), Sarah answers the question normally.
Benchmark#
The Benchmark tab holds test questions with the right answer, so you know how accurate the space is before people rely on it, and after every change.
| Expected | Passes when |
|---|---|
| a value | the answer shows it: a number within 0.5% (128450.75, 12%) in a tile or a small result, or the same word (Store 12) |
| SQL | one of the answer's queries returns the same rows as your SQL; the order of rows and columns does not matter, extra columns are fine |
Run asks every question in the space, as you, and shows the accuracy with each question's result and the reason (expected 1250; the answer's first figure was 1180). Runs are kept, so you can see accuracy go up as you add instructions, terms and trusted answers. A run does not save its answers to your reports.
Cost of a run: one Sarah answer per question (the model tokens, shown on the run) plus its queries on the cluster that is already running; nothing new is started.
Fix queue#
A thumbs-down in the space lands in its owner's Fix queue with the question, the SQL and the answer, and the note the person wrote. Fix each one so the next answer is right:
- an instruction: added to the space's instructions;
- a term: added to (or replacing) a business term;
- a trusted answer: the answer as it was, or with corrected SQL;
- a benchmark question: so the fix is checked on every run.
Or Dismiss it. Resolved items stay listed under show resolved.
Suggested fixes#
The Suggested fixes tab does the first step of the fix queue for you. When a thumbs-down lands in the queue, or a benchmark question misses, the assistant reads the question, the wrong answer, its SQL and the space as it is now, and proposes one change with a one-line reason:
- add a business term (the word, what it means, its SQL),
- add an instruction,
- add a trusted answer (the question and its SQL; it may only read the space's own tables, one SELECT or WITH),
- or add a benchmark question, when the space itself is right.
When the right answer is known (a benchmark miss, or you type it in), the suggestion also brings the question as a new benchmark question, so the fix stays checked.
Each card shows the question, the answer that was given, the problem in plain words and the change as a diff. Click Test & apply or Reject:
- Test & apply never applies an untested change. The space's benchmark runs with the change held in memory; nothing is saved while it runs. The change is applied only if accuracy is not lower than the latest benchmark run, the missed question (for a benchmark miss) now passes, and the new benchmark question passes. If the space has no benchmark yet, the suggestion must bring its test question, and that question must pass. The card then shows accuracy before → after, and applied or not applied with the reason. An applied fix also closes its fix-queue item.
- Reject marks it rejected; nothing changes.
You can also pick a fix-queue item and click Suggest yourself. Suggestions are made in the background and never slow an answer down. At most one is open per fix-queue item or missed question, at most 20 a day for one space, and Suggest automatically switches them off for the space. Only the space's owner or an administrator sees the tab.
What it costs: one model call per suggestion, and on Test & apply one benchmark run (about one answer per benchmark question, plus one more run when the latest run is older than today's questions).
Agents can ask a space#
Agents ask a space with the ask_space tool: the space (its id or name), the question, and optionally a deep answer. The answer comes through the same path as the Sarah page, as the person talking to the agent: their grants, row filters and masks apply, and the space must be one they may use (theirs, shared with them or a group of theirs, or with everyone). The agent gets back the answer and key figures, the SQL behind them, the Trusted badge when a trusted answer gave it, and the cost. These answers are not saved to the person's reports.
- In Agent Studio: tick ask_space, then tick the spaces it may ask. A saved agent asks only those, and never a space the person talking to it cannot use.
- The built-in agent may ask any space the person may use.
A full walk-through with screenshots, from a new space to an agent and a supervisor that ask it: Demo Agents — a practical guide.
Move a space to another environment#
A space travels like an agent: as spaces/<name>.yaml through Git (Deployment → Git panel), or as Space on the Deployment screen's Compare. The file holds the tables, instructions, terms, starter questions, shares, trusted answers (question and SQL) and benchmark questions; never the owner, answers or the fix queue. The receiving environment matches the space by name. See Git integration.
Try it: Retail store sales#
- ML & AI → Spaces → New: name Retail store sales, table
gold.dbt_retail_daily_store_sales. - Instructions: Sales are in USD. "Last week" is the last full Monday-to-Sunday week.
- Term: net sales =
SUM(net_sales). - Starter question: Net sales by store for the latest day.
- On Sarah, choose Retail store sales and ask the starter question. Press Save as trusted.
- Ask net sales by store for the latest day again: the answer shows Trusted.
- On Benchmark, add Total net sales for the latest day with the expected value from the answer's tile, and Run.
For developers#
| Endpoint | What it does |
|---|---|
GET /api/spaces/tables |
Gold and Silver tables a space can hold |
GET /api/spaces / POST /api/spaces |
spaces I can use / create {name, description, tables, instructions, terms, starterQuestions} |
GET /api/spaces/:id / PATCH /api/spaces/:id |
one space / change it (owner or admin; status: "archived") |
GET /api/spaces/:id/shares / POST …/shares |
{add: [{kind: user|group|everyone, principal}], remove: [...]} |
POST /api/spaces/:id/ask/stream |
{question, history?, deep?, maxSteps?, tokenBudget?}: the same events as /api/sarah/ask/stream, then {type: "cost"} |
GET/POST /api/spaces/:id/trusted, PATCH/DELETE …/trusted/:tid |
trusted answers {question, sql, params} |
POST /api/spaces/:id/trusted/from-report |
{reportId}: one click from an answer |
GET/POST /api/spaces/:id/benchmarks, PATCH/DELETE …/:cid |
benchmark questions {question, expectedKind: value|sql, expected} |
POST /api/spaces/:id/benchmarks/run |
starts a run, answers {runId} at once |
GET /api/spaces/:id/benchmarks/runs, GET /api/spaces/benchmark-runs/:runId |
run history / one run's results |
POST /api/spaces/:id/feedback |
{reportId, rating: up|down, note?} |
GET /api/spaces/:id/fix-queue, POST …/fix-queue/:fid |
the queue / resolve {action: instruction|term|trusted|benchmark|dismiss, …} |
A gate (for example an agent release check) calls the benchmark from code:
import { runSpaceBenchmark } from './server/lib/spaces.js';
const { accuracy, cases, passed, results } = await runSpaceBenchmark(tenantId, spaceId, callerCtx);
callerCtx is the asking person's context (userId, username and their session cookie), so every query runs under their access.
Tables (migration server/migration-scripts/create-sarah-spaces.js, every row carries tenantid): sarah_spaces, sarah_space_shares, sarah_space_trusted, sarah_space_bench_cases, sarah_space_bench_runs, sarah_space_bench_results, sarah_space_feedback.