KQ-2078 · QUERY/STAGES
Query Stages
A database query call shown as the stages it runs through, in the order the database runs them: as each finishes its clause lights, its bar narrows from the previous stage's width to its own on springs.snap and its row counter falls on snap, so the stack of bars reads as a funnel, while the running clause carries a sweeping underline and the result table unfolds beneath on springs.glide with its rows in a cascade once the last clause is done. Slow stages show their time and note, an empty result names the clause that removed the last rows, and a syntax error outlines its clause and underlines the token. Tab moves between the clauses and the table, and Enter on a clause opens the rows as they stood after it.
KQ-2078 · QUERY/STAGES
Coldbrook ops · which items are short in the North warehouses
run_querycoldbrook-stockStage 1 of 6
running · stage 1 · coldbrook stock
Install
One command — the source lands in your repo. Or copy it from the Code tab.
$ pnpm dlx shadcn@latest add @kinetiq/query-stages
Props
- stageStyle
- "funnel" | "bars" | "rail"
- default "funnel"
- Bars centred so the stack reads as a funnel, bars from the left like a chart, or a rail of stage nodes that fills as the query runs.
- counterStyle
- "roll" | "tally" | "share"
- default "roll"
- Rolling digit columns, a number that tallies down, or the share of the source rows with the count beneath.
- accent
- string
- default "var(--accent-bright)"
- Lit keywords, bars, the running underline and the table rule — any CSS colour.
- source
- { tool: string; database: string }
- default { tool: "run_query", database: "coldbrook-stock" }
- The tool that ran the query and the database it ran on.
- statement
- string
- default defaultQueryStatement
- The statement as written; Copy writes it to the clipboard and Copy and Explain hand it over.
- stages
- QueryStage[]
- default defaultQueryStages
- The clauses in run order: id, clause (from, join, where, group, having, select, order, limit), text, rows left, ms, note and a sample of rows.
- columns
- QueryColumn[]
- default defaultQueryColumns
- The result's columns: key, label, align, width, and hideNarrow to drop one on a phone.
- rows
- QueryRow[]
- default defaultQueryRows
- The result rows.
- status
- "loading" | "running" | "done" | "error"
- default "done"
- Where the call is. Rendered done, the view arrives finished with no travel.
- completed
- number
- default stages.length
- How many stages have finished while running; the next one is lit as running.
- error
- QueryStagesError | null
- default null
- A syntax error with status "error": the stage id, the message, the token to underline and the line.
- slowMs
- number
- default 1000
- A stage slower than this is marked slow and shows its note, in ms.
- onRerun
- () => void
- default —
- Re-run in the header.
- onOpenResult
- (rows: QueryRow[]) => void
- default —
- Open in the result's header, with every row.
- onCopyQuery
- (statement: string) => void
- default —
- Copy in the header, with the statement.
- onExplain
- (statement: string) => void
- default —
- Explain in the header, with the statement.
- onInspectStage
- (stage: QueryStage) => void
- default —
- Enter or a click opened a finished stage's rows.
- format
- (n: number) => string
- default en-US grouping
- Formats every row count and number cell.
- tableRows
- number
- default 4
- Result rows visible before the table scrolls inside its own region.
- label
- string
- default "<tool> on <database>"
- The view's accessible name.
- className
- string
- default —
- Classes for the outer surface.
| Prop | Type | Default | Description |
|---|---|---|---|
| stageStyle | "funnel" | "bars" | "rail" | "funnel" | Bars centred so the stack reads as a funnel, bars from the left like a chart, or a rail of stage nodes that fills as the query runs. |
| counterStyle | "roll" | "tally" | "share" | "roll" | Rolling digit columns, a number that tallies down, or the share of the source rows with the count beneath. |
| accent | string | "var(--accent-bright)" | Lit keywords, bars, the running underline and the table rule — any CSS colour. |
| source | { tool: string; database: string } | { tool: "run_query", database: "coldbrook-stock" } | The tool that ran the query and the database it ran on. |
| statement | string | defaultQueryStatement | The statement as written; Copy writes it to the clipboard and Copy and Explain hand it over. |
| stages | QueryStage[] | defaultQueryStages | The clauses in run order: id, clause (from, join, where, group, having, select, order, limit), text, rows left, ms, note and a sample of rows. |
| columns | QueryColumn[] | defaultQueryColumns | The result's columns: key, label, align, width, and hideNarrow to drop one on a phone. |
| rows | QueryRow[] | defaultQueryRows | The result rows. |
| status | "loading" | "running" | "done" | "error" | "done" | Where the call is. Rendered done, the view arrives finished with no travel. |
| completed | number | stages.length | How many stages have finished while running; the next one is lit as running. |
| error | QueryStagesError | null | null | A syntax error with status "error": the stage id, the message, the token to underline and the line. |
| slowMs | number | 1000 | A stage slower than this is marked slow and shows its note, in ms. |
| onRerun | () => void | — | Re-run in the header. |
| onOpenResult | (rows: QueryRow[]) => void | — | Open in the result's header, with every row. |
| onCopyQuery | (statement: string) => void | — | Copy in the header, with the statement. |
| onExplain | (statement: string) => void | — | Explain in the header, with the statement. |
| onInspectStage | (stage: QueryStage) => void | — | Enter or a click opened a finished stage's rows. |
| format | (n: number) => string | en-US grouping | Formats every row count and number cell. |
| tableRows | number | 4 | Result rows visible before the table scrolls inside its own region. |
| label | string | "<tool> on <database>" | The view's accessible name. |
| className | string | — | Classes for the outer surface. |