Back to the index · Previous: Reference
How it works#
Sarah turns one question in plain words into an analytics report. You type (or say) "sales by region this quarter versus last"; she reads the business views of your Gold layer and the approved Semantics definitions, writes the SQL, runs it under your own access rights, and shows a report: four or five headline tiles, the charts, and a short analysis folded away underneath. Nothing on the page is typed in by hand: every number comes from a query you can open.
Four rules hold for every report:
- Gold only. Every query reads
datasimple.gold.<view or table>. A query that names a Bronze, Silver or Source table, or a file path, is rejected before it runs and sent back to be corrected. - Never deletes. Sarah reads. She never drops, deletes, truncates or alters anything, for anyone; see AI guardrail.
- Your access, not Sarah's. Queries run through the same Spark SQL endpoint as a notebook cell, as you. Grants, row filters and column masks apply unchanged, also when Sarah reads a business view (a view is read through its tables). There is no Sarah superuser.
- Traceable. The report keeps the SQL, timing and rows of every query. Details opens them; a question that asks for details ("show the breakdown", "list all rows") opens them by itself.
Approved Semantics metrics are used when they answer the question, and the chart shows a green shield. A business word with no approved definition is computed from the Gold columns, flagged with an amber shield, and the assumption is listed in the analysis notes.
Business views: what Sarah answers from#
People never see Gold table names. Each star schema (a fact and its dimensions) or One Big Table has one business view in Gold, for example gold.retail_sales_view, with a business name (Retail sales) and its meaning saved with it: one row per what, which numbers add up and which are averaged (prices, %), the date column and how it can be sliced. The empty Sarah page shows these as cards under What Sarah can answer from, with a search box when there are many.
- Views are made automatically when an engineer builds a star with
ds.fact/ds.obt(DS Tables), and refreshed on every build. - Refresh business views on the Sarah page builds or refreshes them by hand (it needs permission to create tables in Gold).
- With many models, Sarah works with the 40 closest to the question.
- One report can use several business models of the same area (sales with store traffic, production with quality). Numbers from two models are only combined on the columns they share (date, store, plant, product), each side summed to that level first, so totals are never inflated.
Steps#
Left rail → Sarah. The sound-wave on the left of the box is Sarah: it ripples while she waits, moves with your voice while you speak, pulses while she reads the catalog and runs the queries, and comes alive while she writes.
Type a question and press Enter, or press Let's talk and talk to Sarah. Example questions appear under the box, built from your business models and approved metrics, never from table names.
Talking to Sarah. When an administrator has set up live voice on the server, she hears and speaks at the same time, so you can talk over her. Without it, or if the voice service refuses the session, she uses the browser's own voice in Chrome or Edge. It's a conversation, not dictation: small talk stays small talk, and a data question starts a report. When the report is ready it appears on screen straight away and Sarah reads its summary. "Any update?" tells you where a report stands. Voice settings (the slider icon in the ask bar once a report is open) sets what Sarah calls you and her personality; personality changes how she talks, never the numbers. A voice session ends after 5 minutes of silence or 15 minutes in total.
While she works, the bar shows the phase (understanding, probing, running the queries, writing) and one chip per query with its row count and time.
Read the report top to bottom:
- the title and one answer sentence, with chips for the business model it came from, the period and the approved metrics;
- 4 to 5 small tiles: the headline numbers with their change (a tile with no data yet says Not loaded yet);
- the charts; each shows only its title, and hovering it tells what the query is and why this chart was chosen;
- Analysis notes, closed by default: the findings, What stands out and the notes. An amber number on it counts the notes. The page remembers whether you keep it open.
Refine with a follow-up in the same box: "now split by product", "only the top five", "year over year instead". The previous question and report go back with the new one. The + in the ask bar starts a new question.
Details shows every query: purpose, SQL, status, rows and time, and the full result (up to 1,000 rows kept). Probes Sarah ran before planning (date ranges, distinct values) are listed too.
The report is saved. Recent reports on the right reopens any report exactly as shown. The link button copies a URL (
?sarah=<id>) that opens it directly.
Charts: change the format, filter by a few dimensions#
Format. Each chart card has a small icon switcher at the top right: line, area, bars, stacked bars, heatmap, pie, table. Only formats that fit the data are offered: stacked bars and heatmap need a split into groups, a pie needs a few categories (not dates). The choice is yours and is not saved with the report.
Filters. Each chart offers at most three dropdowns for the main dimensions of its business model, for example All store formats · All regions · All departments or Plant · Category · Line. Picking a value runs that chart's query again on the server, under your access, so the numbers are exact; a trend's forecast is recalculated too. ✕ clears the filters. Only main dimensions are offered (never codes or ids, nothing with more than 40 values); anything finer is a question for Sarah. The tiles at the top do not change with a chart filter.
Forecasts#
Ask "forecast net sales for the next 3 months", or look at a trend: when its data is fit, Sarah extends the trend line with a dashed forecast and a shaded likely range (80%), with a chip such as Forecast with care · ±2% tested. Why? opens the checklist Sarah ran first:
| Check | Why it matters |
|---|---|
| A date column at day, week, month, quarter or year | no time series, no forecast |
| Enough history (12 months for a trend; two full years for a yearly pattern) | short history gives a wobbly trend |
| No gaps; an unfinished latest period is left out | a missing or half month distorts the forecast |
| The measure adds up (sales, quantity); a rate or average is flagged | rates are forecast through their parts |
| No sudden change in level (new stores, a price change) | only data after the change is used |
| Not mostly zeros; data is fresh | too sparse or stale data is not forecast |
Sarah then tests several standard methods on the latest periods held out, keeps the most accurate, and states its error. When the data is not fit, she says why and what would fix it instead of giving a number. A forecast is always an estimate, never an approved metric.
A period still running (this month, on the 14th) is not learned from, but it is forecast: it is drawn as a hollow marker with its value so far, listed in the forecast table as running, … so far, and counted in the total. The total, its likely range and the forecast table always cover the same periods, so the total sits inside its range and the table rows add up to it. The same rule is used by Everything, ML & AI → Forecast and ds.ml.forecast.
Sarah and notebooks#
- Open in notebook. The Notebook button on a report creates a notebook with an introduction (question, date, models) and one SQL cell per query, and opens it. The queries run again under the opener's own access. The notebook shows Back to the Sarah report at the top, and pressing Notebook on the report again reopens the same notebook.
- Share with Sarah. On a notebook SQL result, Share with Sarah asks for a business name and a one-sentence meaning, then saves the result as a Gold table (
gold.shared_<name>) with its own business view, so Sarah can answer from it. The rows saved are the ones the sharer can see (their access rules apply); everyone allowed to read Gold then sees those rows. It needs permission to create tables in Gold, and a result someone else shared is not overwritten. - Sarah herself never reads or runs notebooks: notebook results reach her through Gold.
What the widgets mean#
| Widget | Shows | When it is used |
|---|---|---|
| KPI tile | one number, the comparison value, the change in percent | always, four or five of them |
| Line / area / bar | a measure over time or over a category, one line or bar per series | a trend, or a breakdown |
| Forecast | actuals, a dashed forecast, the likely range and the readiness checks | a forecast question, or a trend whose data is fit |
| Compare | one measure in two periods side by side per label, with the change | "versus last quarter", "year over year" |
| Heatmap | two categorical dimensions that really cross, darker is larger | region × product, month × category |
| Map | one tile per US state or country, darker is larger; other region names become ranked tiles | a geographic dimension |
| Table | the rows themselves | you asked for details, a list or a breakdown |
| Scatter | one dot per row, one measure against another | two measures and many rows (price against volume) |
| Histogram | how values are spread, in bins | one measure and many rows (order sizes) |
| Waterfall | from the previous total to the current one, item by item | you asked why something changed and there is a comparison |
| Funnel | stages, each with its share of the first and of the one before | stages that shrink (visited, added to cart, paid) |
Headline tiles. Sarah plans four or five. When she plans fewer, the row is filled from the report's own charts: the latest complete period with its change on the one before, the total, the best period, the forecast total and the top item with its share; never a number a tile already shows. Hovering such a tile names the chart it came from.
The data decides the chart. Sarah proposes the widgets; then the server looks at what each query returned and picks the chart from its shape, overriding a poor pick: data over time is a line (a stacked area when split into up to five groups, bars when there are only two points), a ranking of more than ten is bars with the top ten and the rest as Other, a donut is used only for up to six parts of one whole when the question is about share, two categories that really cross make a heatmap (a store and its one region is a list, not a grid; a code and its name count as one category), and two different measures are bars side by side, never a percentage change. Duplicates are dropped; a report keeps at most five tiles and four charts. The rules are in server/lib/chart-decider.js, with tests.
What stands out. In the analysis notes, a short list of patterns read from the data, never invented: the trend (up 23% from Jan 2025 to Jun 2025), an unusual point (Dec 2025 stands out: 1.5× the usual level), a missing period (no data for Oct 29; changes across it are not day-on-day), what drove a change, concentration, a weekday pattern, and the forecast with its error. The summary is written with these in hand, so the two agree.
Today and yesterday. A table with one row per day has no time of day, even when its date is stored as a timestamp, so "today versus yesterday" is compared with all of yesterday and the tile says so. When today has no rows yet, Sarah says so and reports the latest complete day.
Colours mean the same thing on every report: one blue ramp for magnitude, a fixed order of hues for series, green and red with an arrow for a change.
Answer receipt#
Every answer has a Receipt button, next to Details. It shows how the answer was made, so anyone checking it can see what it rests on:
- Who asked and when, the question, and the one-line answer.
- Tables read, taken from the SQL that ran: for each one, when its data last changed and by whom or what (updated 2 h ago by RTL 04 notebook), its row count, the tables it is built from one step up, whether a row filter or a column mask applied to you, and its latest data-quality result.
- The SQL of every query (open a line to see it), with its row count or the error.
- Versions: the space and its owner, the trusted answer used (if any) and a deep answer's steps.
- Cost: dollars, tokens and time taken.
- Verified: chain intact. Receipts can only be added, never changed or removed. Each one carries a fingerprint of its content and of the receipt before it, so a receipt changed afterwards shows Not verified. An administrator can check every receipt of the workspace at once (
GET /api/receipts/verify).
Receipts cover plain answers, answers in a space, trusted answers and deep answers. A receipt is shown to the person who asked, the owner of the space, and administrators, inside the same workspace only.
Cost: a receipt adds no model call and no query on the lake. It is written just after the answer is shown, from what the answer already recorded, with a few small reads of the application database; the answer never waits for it, and if it cannot be written the answer is not affected.
Administration#
- Tab access. Sarah is the
sarahtab key (Administration → Roles → Screens). Administrator roles with no saved tab list see it; a role with an explicit list needs it enabled. The API behind it is/api/sarah. - LLM key. Sarah uses the same provider as the Agent:
ANTHROPIC_API_KEYorOPENAI_API_KEY(AGENT_PROVIDER,AGENT_MODELto pin one). Without a key the page says so and the Ask button is disabled. - Limits.
SARAH_TIMEOUT_MS(default 240000) andSARAH_MAX_TURNS(default 7) bound one ask. Each query returns at most 500 rows to a widget; the report keeps up to 1,000 rows per query. - Business views.
POST /api/sarah/models/sync(the Refresh business views link) builds or refreshes them as the caller;GET /api/sarah/modelslists them. Old test stars get views too when refreshed without a filter; a view can be dropped like any other. - Audit. Every ask writes
sarah.ask; refreshing business views writessarah.models_sync; sharing a result writessarah.share. Every query Sarah runs is a normalnotebook.spark_runby the asking user. - Storage. Reports live in
sarah_reports(one row per answered question, the whole report as JSON, scoped by tenant). The table is created on first use.
Previous: 13. Reference · Next: 15. DS Tables · Back to the index