Skip to content

In this tutorial, you’ll add a chart to the project the Quickstart left you. You’ll ask the same question from a script, run the SQL yourself, let the model pick a chart without showing it a row, and draw that chart with ECharts. At the end, a chart of what each customer spent is open in your browser.

You draw with ECharts here, but AskDB isn’t tied to it. AskDB returns a chart spec, and any charting library can draw it. The one piece you write for your library is a small function that maps the spec to that library’s config. Step 4 of Chart a query result has it for two libraries, in the tabs “ECharts” and “shadcn/ui (Recharts)”.

You need:

  • The project from the Quickstart, in its askdb-shop folder. It holds shop.db, the askdb/ folder and .env. Run every command on this page in that folder.
  • An OpenAI API key in .env, which is what the Quickstart’s steps set up. If you chose Anthropic or Google there, Bring your own model shows how to build that provider’s model for step 1.

The two files you’ll write, first-chart.mjs and to-echarts.mjs, are in examples/chart-a-result. Compare yours with them if a step doesn’t work.

The output on this page is from one recorded run of that example’s chart.mjs, with gpt-4o-mini on 2026-11-15. The model writes the SQL and the chart’s title, so yours can differ.

In the Quickstart, you asked with the askdb ask command and piped the SQL into run-query.mjs. A chart needs the question, the SQL and the rows in one place, so now you’ll do both from one script.

First, add the packages the script uses:

Terminal window
npm install @askdb/client @askdb/core ai @ai-sdk/openai echarts

@askdb/core has ask(), which returns checked SQL as askdb ask does. @askdb/client has the chart functions. ai and @ai-sdk/openai build the model, and ECharts draws the chart.

Now create first-chart.mjs:

first-chart.mjs
import { DatabaseSync } from "node:sqlite";
import { openai } from "@ai-sdk/openai";
import { ask, loadSchema } from "@askdb/core";
const question = "How much has each customer spent in total, highest first?";
const model = openai(process.env.OPENAI_MODEL || "gpt-4o-mini"); // reads OPENAI_API_KEY
// 1. AskDB returns the SQL. Your own code runs it.
const { sql } = await ask({ question, schema: loadSchema("./askdb"), model, dialect: "sqlite" });
const statement = new DatabaseSync("shop.db", { readOnly: true }).prepare(sql);
const rows = statement.all().map((row) => ({ ...row })); // plain objects, for ECharts in step 4
console.log(sql);
console.table(rows);

The script builds the model from the key in .env and asks your question. Then it runs the SQL on shop.db, read-only, as run-query.mjs did. Run it:

Terminal window
node --env-file=.env first-chart.mjs

--env-file=.env gives the script the API key you put in .env in the Quickstart. The output should look something like this:

SELECT customers.name, SUM(products.price * orders.quantity) AS total_spent
FROM customers
JOIN orders ON customers.id = orders.customer_id
JOIN products ON orders.product_id = products.id
GROUP BY customers.id
ORDER BY total_spent DESC;
┌─────────┬────────────┬─────────────┐
│ (index) │ name │ total_spent │
├─────────┼────────────┼─────────────┤
│ 0 │ 'Grace' │ 398 │
│ 1 │ 'Margaret' │ 377 │
│ 2 │ 'Ada' │ 138.99 │
│ 3 │ 'Linus' │ 49.99 │
└─────────┴────────────┴─────────────┘

That’s the Quickstart’s answer again, this time from your own script. Notice that the script keeps the rows in rows. The next steps use them, and the model never gets them. On Node 22, Node also prints an ExperimentalWarning about SQLite, as it did in the Quickstart.

To pick a chart, you need to know what each column holds: names to group by, or numbers to plot. classifyResult() works that out in your own process, with no model call. Add the highlighted lines:

  • The import from @askdb/client/charts, which also brings in planChart for step 3.
  • The lines under the // 2. comment.
first-chart.mjs
import { DatabaseSync } from "node:sqlite";
import { openai } from "@ai-sdk/openai";
import { classifyResult, planChart } from "@askdb/client/charts";
import { ask, loadSchema } from "@askdb/core";
const question = "How much has each customer spent in total, highest first?";
const model = openai(process.env.OPENAI_MODEL || "gpt-4o-mini"); // reads OPENAI_API_KEY
// 1. AskDB returns the SQL. Your own code runs it.
const { sql } = await ask({ question, schema: loadSchema("./askdb"), model, dialect: "sqlite" });
const statement = new DatabaseSync("shop.db", { readOnly: true }).prepare(sql);
const rows = statement.all().map((row) => ({ ...row })); // plain objects, for ECharts in step 4
console.log(sql);
console.table(rows);
// 2. Classify the columns, here in your own process.
const columns = statement.columns().map(({ name }) => ({ name }));
const result = classifyResult({ columns, rowCount: rows.length, rows });
console.log(result.shape);

Run the script again, with the same command as in step 1. After the SQL and the rows, it now prints this:

{
columns: [
{ name: 'name', kind: 'category' },
{ name: 'total_spent', kind: 'currency' }
],
rowCount: 4,
truncated: false
}

name is a category, and total_spent is currency. Notice what isn’t here: no Grace, no 398. The column names, their kinds and the row count are all the model will get of your result.

Now you pass planChart() the question, the SQL and that classified result, with the same model that wrote the SQL. Of the result, only its shape reaches the model. Add the highlighted lines, the ones under the // 3. comment:

first-chart.mjs
import { DatabaseSync } from "node:sqlite";
import { openai } from "@ai-sdk/openai";
import { classifyResult, planChart } from "@askdb/client/charts";
import { ask, loadSchema } from "@askdb/core";
const question = "How much has each customer spent in total, highest first?";
const model = openai(process.env.OPENAI_MODEL || "gpt-4o-mini"); // reads OPENAI_API_KEY
// 1. AskDB returns the SQL. Your own code runs it.
const { sql } = await ask({ question, schema: loadSchema("./askdb"), model, dialect: "sqlite" });
const statement = new DatabaseSync("shop.db", { readOnly: true }).prepare(sql);
const rows = statement.all().map((row) => ({ ...row })); // plain objects, for ECharts in step 4
console.log(sql);
console.table(rows);
// 2. Classify the columns, here in your own process.
const columns = statement.columns().map(({ name }) => ({ name }));
const result = classifyResult({ columns, rowCount: rows.length, rows });
console.log(result.shape);
// 3. Ask the model which chart fits. It gets the question, the SQL and result.shape.
const plan = await planChart({ question, sql, result, model, dialect: "sqlite" });
console.log(plan);

Run the script again. It makes a second model call, and then prints the plan:

{
primary: {
type: 'horizontal-bar',
category: 'name',
series: [ 'total_spent' ],
title: 'Total Spending by Customers (Highest First)',
description: 'Displays the total amount spent by each customer, ranked from highest to lowest.'
},
source: 'model',
latencyMs: 1287
}

primary is a chart spec. It names a chart type, the column for the labels (category), the columns to plot (series), a title and a description. It holds no rows, and it draws nothing. Drawing is your job, as running the SQL was. source says the model picked this chart, and latencyMs says how long that took.

ECharts draws from an option object, so you need a function that turns a chart spec into one. This function is the only part of the tutorial that’s tied to ECharts. For shadcn/ui, the “shadcn/ui (Recharts)” tab in step 4 of the guide has the same mapping as a React component. Create to-echarts.mjs:

to-echarts.mjs
/**
* Turns a chart spec from @askdb/client/charts into an ECharts option.
* ECharts reads your rows from `dataset.source` and picks columns by name with `encode`,
* so the spec's `category` and `series` go in as they are.
* A metric is one number, not a chart: it gets no option.
*
* @param {import("@askdb/client/charts").ChartSpec} spec
* @param {Record<string, unknown>[]} rows
* @returns {import("echarts").EChartsOption | null}
*/
export function toEChartsOption(spec, rows) {
if (spec.type === "metric") return null;
const base = {
title: { text: spec.title, subtext: spec.description },
dataset: { source: rows },
tooltip: {},
};
if (spec.type === "pie") {
return { ...base, series: [{ type: "pie", encode: { itemName: spec.category, value: spec.series[0] } }] };
}
const horizontal = spec.type === "horizontal-bar";
const categoryAxis = { type: "category", inverse: horizontal }; // inverse: the first row at the top
const valueAxis = { type: "value" };
return {
...base,
legend: { show: spec.series.length > 1, bottom: 0 },
grid: { top: 80 },
xAxis: horizontal ? valueAxis : categoryAxis,
yAxis: horizontal ? categoryAxis : valueAxis,
series: spec.series.map((column) => ({
type: spec.type === "line" || spec.type === "area" ? "line" : "bar",
name: column,
...(spec.type === "area" ? { areaStyle: {} } : {}),
encode: horizontal ? { x: column, y: spec.category } : { x: spec.category, y: column },
})),
};
}

It has a path for each chart type a chart spec can name. Your chart spec takes the horizontal-bar path: one bar per row, with the names down the side.

Now draw the chart from your rows. Add the highlighted lines to first-chart.mjs: the three new imports, and the lines under the // 4. comment.

first-chart.mjs
import { writeFileSync } from "node:fs";
import { DatabaseSync } from "node:sqlite";
import { openai } from "@ai-sdk/openai";
import { classifyResult, planChart } from "@askdb/client/charts";
import { ask, loadSchema } from "@askdb/core";
import * as echarts from "echarts";
import { toEChartsOption } from "./to-echarts.mjs";
const question = "How much has each customer spent in total, highest first?";
const model = openai(process.env.OPENAI_MODEL || "gpt-4o-mini"); // reads OPENAI_API_KEY
// 1. AskDB returns the SQL. Your own code runs it.
const { sql } = await ask({ question, schema: loadSchema("./askdb"), model, dialect: "sqlite" });
const statement = new DatabaseSync("shop.db", { readOnly: true }).prepare(sql);
const rows = statement.all().map((row) => ({ ...row })); // plain objects, for ECharts in step 4
console.log(sql);
console.table(rows);
// 2. Classify the columns, here in your own process.
const columns = statement.columns().map(({ name }) => ({ name }));
const result = classifyResult({ columns, rowCount: rows.length, rows });
console.log(result.shape);
// 3. Ask the model which chart fits. It gets the question, the SQL and result.shape.
const plan = await planChart({ question, sql, result, model, dialect: "sqlite" });
console.log(plan);
// 4. Draw the chart yourself, from your own rows.
const chart = echarts.init(null, null, { renderer: "svg", ssr: true, width: 480, height: 300 });
chart.setOption({ ...toEChartsOption(plan.primary, rows), animation: false });
writeFileSync("chart.svg", chart.renderToSVGString());
chart.dispose();
console.log("Wrote chart.svg");

Run the script one last time. The last line of the output is new:

Wrote chart.svg

Open chart.svg in a browser, for example by dragging the file onto a browser window. It should look something like this:

A horizontal bar chart titled Total Spending by Customers (Highest First). Grace 398, Margaret 377, Ada 138.99, Linus 49.99.A horizontal bar chart titled Total Spending by Customers (Highest First). Grace 398, Margaret 377, Ada 138.99, Linus 49.99.
The chart from the recorded run, drawn by ECharts from that run’s 4 rows. The model picked the horizontal bars, the two columns and the title, with gpt-4o-mini on 2026-11-15.

That’s your chart. ECharts drew it from the four rows your own code read from shop.db. The model chose the bars, the columns and the title, and it never saw a row.

You asked a question from a script and ran the SQL yourself. classifyResult() described the columns in your own process. planChart() had the model pick a chart from that description, and ECharts drew the chart from your rows. AskDB returned the SQL and the chart spec. Your code did the running and the drawing.

ECharts is this tutorial’s choice, not AskDB’s. To draw with another library, replace to-echarts.mjs with a function that maps the same chart spec to that library’s config. Step 4 of Chart a query result has that mapping for shadcn/ui charts, which are Recharts, in its “shadcn/ui (Recharts)” tab. Its “ECharts” tab is this tutorial’s function. It also names the matching settings in Chart.js and Vega-Lite.

Try another question. Change question to “How many units of each product were sold?”, run the script, and open chart.svg again. The script draws any answer that has rows to group and a number to plot. Any other answer stops with an error at the drawing step, such as one number or one with no chart. Chart a query result handles those.

To hand this task to a coding agent, copy the prompt and paste it into the agent.

Add a chart of a query result to this project by following the tutorial at https://askdb.tools/chart-your-first-answer.md, against this project’s own database and one of its own questions instead of the sample shop database.

The goal: a script that asks the question with ask(), runs the SQL through the project’s own read-only connection, classifies the result with classifyResult(), plans a chart with planChart(), and draws it from the project’s own rows.

Draw with the charting library this project already uses. Look for one in its dependencies first, such as Recharts (shadcn/ui charts are Recharts), Chart.js, ECharts, Vega-Lite or D3. If the project has none, ask which one to add; the tutorial uses ECharts. Then write one function that maps the chart spec to that library’s config, as the tutorial’s to-echarts.mjs does for ECharts: type picks the chart, category and series name columns of the rows, and title and description are its text.

Start from a ready-made mapping when one fits. Step 4 of https://askdb.tools/guides/plan-a-chart.md has two, one in each tab: to-echarts.mjs for ECharts, and components/spec-chart.tsx, a React component for shadcn/ui charts and Recharts. In the AskDB repo they are examples/chart-a-result/to-echarts.mjs and examples/chart-a-result/shadcn/components/spec-chart.tsx.

  • AskDB returns SQL and a chart spec. It runs no SQL and draws nothing: this project’s code does both.
  • Never put a row in a prompt. planChart() gets the question, the SQL and the classified result.
  • @askdb/client/charts is experimental. For an answer that is one number, or that has no chart, follow https://askdb.tools/guides/plan-a-chart.md.

Docs for agentsllms.txtAGENTS.md

© 2026 Yahya Gilany