add_cell
Append a SQL or markdown cell to a QuestDB notebook, returning the new cell ID. Optionally run the cell immediately and receive per-statement status without row data.
Instructions
Append a cell to the notebook. Returns the new cell id and, if run=true, a per-query status array. You never see query rows or column data. Set type:"markdown" to add a prose cell instead of a SQL cell — its sql field then carries the markdown source, it is rendered (never executed), and run is ignored.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run | Yes | If true, run the cell immediately after inserting. Response then includes `ran` (true iff every statement succeeded), `queryCount`, and `results: string[]` — one entry per `;`-separated statement, each `"success"`, `"cancelled"`, or `"ERROR: <message>"`. The order matches the cell's SQL. Still no row data. Pass null to skip. Running is DQL-only: a cell containing DDL/DML (INSERT/UPDATE/CREATE/DROP/...) is added but NEVER executed — the response gets `{ ran: false, skipped: true, note: <reason> }`. Markdown cells (type:"markdown") are likewise never executed. Take consent from the user, then call run_cell explicitly. | |
| sql | Yes | SQL for the cell. May contain multiple statements separated by `;`. In draw mode, multi-statement cells overlay series on a single chart: the first query's timestamp column is the x-axis anchor, subsequent queries contribute additional numeric series merged on the time axis. For a markdown cell (type:"markdown"), this is the markdown source text instead of SQL. | |
| type | Yes | Cell kind. "markdown" creates a rendered prose cell that is never executed (`run` is ignored). null/omitted = "sql". | |
| buffer_id | Yes | ||
| after_cell_id | Yes | Insert after this cell id; pass null to append to the end. |