"Revenue is up 18%." Is it? An AI answer about your data that arrives as one sentence gives the reader nothing to check, so they either trust it blindly or come and ask you.
A good answer has parts. This post takes one real response apart and builds the small panel that shows each part in the right place.
The parts
Here is a real answer from FactQL's public sample data, to the question "Who are our top 5 customers by total spend?":
| Part | Field | Where it goes |
|---|---|---|
| The answer in words | explanation |
On top, always visible |
| The rows it came from |
data.columns, data.rows
|
A table under the answer |
| The query that ran | sql |
Folded away, one click to open |
| Where the numbers came from | lineage.text |
A small line, when present |
The order is the point: answer first for people in a hurry, rows for people who want to check, the query for the one person who needs it.
The code
Two functions. toView shapes the response and has no DOM in it, so you can unit-test it. renderAnswer draws.
// Turn a raw answer into exactly what the panel shows. No DOM here, so it is easy to test.
export function toView(a, maxRows = 10) {
const table = a.data ?? {}; // rows live under "data"
const columns = table.columns ?? [];
const rows = (table.rows ?? []).map((row) =>
row.map((v) => (typeof v === "number" && !Number.isInteger(v) ? Number(v.toFixed(2)) : v)));
return {
ok: a.result === "success",
answer: a.explanation ?? "No answer.",
columns,
rows: rows.slice(0, maxRows),
hiddenRows: Math.max(0, rows.length - maxRows),
query: a.sql ?? null, // folded away by default
source: a.lineage?.text ?? null, // "where the numbers came from", when present
};
}
// The panel itself: answer on top, rows under it, the query behind a click.
export function renderAnswer(a, el) {
const v = toView(a);
const add = (tag, text, parent = el) => { const n = document.createElement(tag); n.textContent = text; parent.append(n); return n; };
el.textContent = "";
add("p", v.answer);
if (v.rows.length) {
const t = add("table", ""), head = add("tr", "", t);
v.columns.forEach((c) => add("th", c, head));
v.rows.forEach((row) => { const tr = add("tr", "", t); row.forEach((cell) => add("td", String(cell), tr)); });
if (v.hiddenRows) add("p", `…and ${v.hiddenRows} more rows`);
}
if (v.source) add("p", v.source);
if (v.query) { const d = add("details", ""); add("summary", "The query that ran", d); add("pre", v.query, d); }
}
Testing the shaping
I ran toView in Node against the real response (18 Nov 2026), with maxRows set to 3:
{
ok: true,
answer: 'Your top 5 customers by total spend are Karl Seal, Tim Cary, Russell Brinson, Harry Arce and Daisy Bates. ...',
columns: [ 'customer_id', 'first_name', 'last_name', 'total_spend' ],
rows: [ [ 526, 'KARL', 'SEAL', 358.12 ], [ 468, 'TIM', 'CARY', 344.06 ], [ 380, 'RUSSELL', 'BRINSON', 324.04 ] ],
hiddenRows: 2,
query: 'SELECT ...',
source: null
}
Five small decisions, and why
-
Round floats for display. The raw value was
358.1200000000005. Nobody wants that in a table. - Cap the rows and say how many are hidden. A table of 4,000 rows is not "showing your work".
-
Use
textContent, neverinnerHTML. Cell values are data. Treat them as text. -
Treat optional parts as optional. In my test
lineagecame backnull, so the panel shows that line only when it exists. - Fold the query. Most readers never open it. The ones who do are the ones who would otherwise message you.
When there's no data answer
The second test case is a response with no rows. toView returns the sentence and empty arrays, and the panel shows just the sentence. No empty table, no broken layout.
What do your users ask for first when they doubt a number: the rows, or the query?
Top comments (0)