Skip to content

feat(query): add query top to monitor running queries - #179

Merged
redox merged 3 commits into
mainfrom
su/query-top
Nov 8, 2026
Merged

redox merged 3 commits into
mainfrom
su/query-top

Conversation

@redox

@redox redox commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Add altertable query top: calls GET /queries, then GET /query/{id} for each running query in parallel (capped at 8 concurrent lookups), and shows start time, elapsed time, progress, processed / estimated rows (X / ~Y), compute size, worker, memory, disk, client, and the statement.
  • -w / --watch redraws on the alternate screen every --interval seconds (default 1, minimum 0.2) until Ctrl+C. When a refresh fails, the last good data stays on screen with the error above it, and rows are trimmed to the terminal height ("… N more").
  • --sort elapsed|progress|rows|memory|disk (largest first, missing values last; default elapsed). It also applies to --json, which returns { queries: [{ id, started_at, details }] } with the raw detail body.
  • A query that finishes between the list call and its lookup (404) stays in the table with its id and start time instead of failing the command.
image Screenshot 2026-11-08 at 09 48 43

Implementation notes

  • API fields are read and type-checked once in toQueryTopRow. A negative percentage means no estimate and shows -; rows show - when nothing has been scanned or estimated.
  • DISK sums worker.memory_by_tag[].temporary_storage_bytes. Summing that array's memory_usage_bytes gives exactly worker.memory_usage_bytes, so MEM uses that field directly.
  • New cli/src/ui/terminal/live-view.ts: a reusable full-screen refresh loop (alternate screen, Ctrl+C, in-place redraw, sleep that Ctrl+C cuts short).
  • DisplayTableColumn gains an optional minWidth so the live view's columns keep their width as values change.
  • One-shot output that isn't going to a terminal keeps full statements instead of cutting the table to 80 columns.

Known limitations

  • Ctrl+C restores the screen immediately, but the process can wait up to the read timeout if a request is still in flight, because sendHttp can't be cancelled yet.
  • The table is wide (about 170 characters before the query text), so on narrow terminals the QUERY column is squeezed.

Test plan

  • bun run check (full gate)
  • altertable query top / --json / --sort rows against an environment with running queries
  • --watch under a pseudo-terminal: redraws every second, Ctrl+C leaves the alternate screen and restores the cursor
  • Try query top -w in a real terminal while a long query runs

🤖 Generated with Claude Code

List running queries with their details fetched in parallel: start time,
elapsed time, progress, processed and estimated rows, compute size,
worker, memory, disk, and client. `--sort` orders by
elapsed|progress|rows|memory|disk; `--watch` (`-w`) redraws on the
alternate screen every `--interval` seconds until Ctrl+C.

The redraw loop lives in a reusable `ui/terminal/live-view.ts`, and
table columns gain an optional `minWidth` so live views do not shift.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
redox and others added 2 commits November 8, 2026 10:13
GitHub no longer supports the macos-14 runner image, so the job was
cancelled before starting and failed the Required check on every run
since Nov 5, main included. The release matrix already uses macos-15.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Track GitHub's current macOS image, like windows-latest, so retiring an
image no longer cancels the job. Release builds stay pinned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@redox
redox merged commit 81ed29e into main Nov 8, 2026
15 checks passed
@redox
redox deleted the su/query-top branch November 8, 2026 09:19
redox pushed a commit that referenced this pull request Nov 8, 2026
🤖 I have created a release *beep* *boop*
---


##
[1.15.0](v1.14.0...v1.15.0)
(2026-11-08)


### Features

* **query:** add `query top` to monitor running queries
([#179](#179))
([81ed29e](81ed29e))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: altertable-release[bot] <345426372+altertable-release[bot]@users.noreply.github.com>
@albert20260301

Copy link
Copy Markdown
Contributor

query top is now available in CLI 1.15.0 on npm and GitHub Releases.

Verified npm archive integrity and the matching GitHub bundle SHA-256. The extracted package reports 1.15.0, returns the expected fixture-based query top --json result, and redraws twice under a pseudo-terminal before Ctrl+C restores the screen and cursor with exit 0. This is artifact/fixture verification, not a live Lakehouse query run.

Upgrade with npm install -g @altertable/cli@1.15.0, then use altertable query top --watch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants