Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/verify.yml
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ jobs:
strategy:
fail-fast: false
matrix:
os: [ubuntu-24.04, macos-14, windows-latest]
os: [ubuntu-24.04, macos-latest, windows-latest]

steps:
- name: Check out revision
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added

- List running queries with `altertable query list`.
- Monitor running queries with `altertable query top`: start time, elapsed time, progress, processed and estimated rows, compute size, worker, memory, disk, and client. Sort with `--sort elapsed|progress|rows|memory|disk`, and add `--watch` (`-w`) to refresh every second until Ctrl+C.
- Preview a single-file data app locally with `altertable app dev --file index.tsx`. The file's `defineDataApp` scope must match the selected profile, and queries run through the CLI's loopback proxy.

### Changed
Expand Down
31 changes: 30 additions & 1 deletion COMMANDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -884,7 +884,7 @@ Run SQL queries against the lakehouse.

```bash
altertable query [options] <STATEMENT>
altertable query list|show|cancel
altertable query list|show|top|cancel
```

**Arguments**
Expand Down Expand Up @@ -914,6 +914,7 @@ altertable query list|show|cancel

- `list` — List running queries in the current environment.
- `show` — Fetch metadata for a completed or running query.
- `top` — Show running queries with progress, rows, and memory; --watch refreshes live.
- `cancel` — Cancel a running query.

**Examples**
Expand All @@ -925,6 +926,7 @@ altertable query "SELECT 1" --format csv --output results.csv
altertable query @report.sql --format csv --output results.csv
altertable query list
altertable query show <query-id>
altertable query top --watch
```

#### `altertable query list`
Expand Down Expand Up @@ -953,6 +955,33 @@ altertable query show <QUERY-ID>
| --- | --- |
| `<QUERY-ID>` | Query id returned by the API Required. |

#### `altertable query top`

Show running queries with progress, rows, and memory; --watch refreshes live.

**Usage**

```bash
altertable query top [options]
```

**Options**

| Option | Description |
| --- | --- |
| `-w, --watch` | Keep refreshing the view until interrupted (Ctrl+C) |
| `--interval <SECONDS>` | Seconds between refreshes in --watch mode Default: "1". |
| `--sort <ELAPSED\|PROGRESS\|ROWS\|MEMORY\|DISK>` | Column to sort by, largest first Values: elapsed, progress, rows, memory, disk. Default: "elapsed". |

**Examples**

```bash
altertable query top
altertable query top --watch
altertable query top -w --interval 5
altertable query top --sort memory
```

#### `altertable query cancel`

Cancel a running query.
Expand Down
2 changes: 1 addition & 1 deletion DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,7 @@ When bumping the `specs/` submodule, extend the mapped tests before merge.
| --------------------------- | ---------------------------- | -------------------------------- | --------------------- |
| POST /query (streamed) | `query "<SQL>"` | `lakehouse.test.ts` stream tests | `integration.e2e.ts` |
| POST /query (buffered json) | `query --json` | `lakehouse.test.ts` | `integration.e2e.ts` |
| GET /queries | `query list` | `lakehouse.test.ts` | — |
| GET /queries | `query list`, `query top` | `lakehouse.test.ts` | — |
| GET/DELETE /query/{id} | `query show`, `query cancel` | `lakehouse.test.ts` | `integration.e2e.ts` |
| POST /append + GET /tasks | `append`, `append status` | `lakehouse.test.ts` | `integration.e2e.ts` |
| POST /upload | `upload` | `lakehouse.test.ts` | `integration.e2e.ts` |
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -398,6 +398,7 @@ inside a component, for example `customer%2E360.main.users`.

```bash
altertable query list
altertable query top --watch
altertable query show <query-uuid>
altertable query cancel <query-uuid> --session-id <uuid>
altertable append status <append-id>
Expand Down
65 changes: 63 additions & 2 deletions cli-reference.json
Original file line number Diff line number Diff line change
Expand Up @@ -1526,7 +1526,7 @@
"description": "Run SQL queries against the lakehouse.",
"usage": [
"altertable query [options] <STATEMENT>",
"altertable query list|show|cancel"
"altertable query list|show|top|cancel"
],
"aliases": [],
"arguments": [
Expand Down Expand Up @@ -1686,7 +1686,8 @@
"altertable query \"SELECT 1\" --format csv --output results.csv",
"altertable query @report.sql --format csv --output results.csv",
"altertable query list",
"altertable query show <query-id>"
"altertable query show <query-id>",
"altertable query top --watch"
],
"subcommands": [
{
Expand Down Expand Up @@ -1727,6 +1728,66 @@
"examples": [],
"subcommands": []
},
{
"id": "altertable-query-top",
"command": "altertable query top",
"description": "Show running queries with progress, rows, and memory; --watch refreshes live.",
"usage": [
"altertable query top [options]"
],
"aliases": [],
"arguments": [],
"options": [
{
"name": "watch",
"aliases": [
"w"
],
"type": "boolean",
"description": "Keep refreshing the view until interrupted (Ctrl+C)",
"required": false,
"repeatable": false,
"scope": "command",
"values": []
},
{
"name": "interval",
"aliases": [],
"type": "string",
"description": "Seconds between refreshes in --watch mode",
"required": false,
"repeatable": false,
"scope": "command",
"values": [],
"valueHint": "SECONDS",
"default": "1"
},
{
"name": "sort",
"aliases": [],
"type": "enum",
"description": "Column to sort by, largest first",
"required": false,
"repeatable": false,
"scope": "command",
"values": [
"elapsed",
"progress",
"rows",
"memory",
"disk"
],
"default": "elapsed"
}
],
"examples": [
"altertable query top",
"altertable query top --watch",
"altertable query top -w --interval 5",
"altertable query top --sort memory"
],
"subcommands": []
},
{
"id": "altertable-query-cancel",
"command": "altertable query cancel",
Expand Down
2 changes: 1 addition & 1 deletion cli/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ altertable
├── catalog
│ └── create
├── query <SQL>
│ └── list, show, cancel
│ └── list, show, top, cancel
├── schema, duckdb
├── append <DATA>
│ └── status
Expand Down
2 changes: 1 addition & 1 deletion cli/scripts/command-reference.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ describe('command reference', () => {
const reference = renderCommandReferenceMarkdown(await resolveReference());

expect(reference).toContain(
'```bash\naltertable query [options] <STATEMENT>\naltertable query list|show|cancel\n```'
'```bash\naltertable query [options] <STATEMENT>\naltertable query list|show|top|cancel\n```'
);
expect(reference).toContain('```bash\naltertable profile env [NAME]\n```');
expect(reference).toContain(
Expand Down
3 changes: 3 additions & 0 deletions cli/src/commands/query/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { queryRunArgs } from '@/commands/query/lib/args.ts';
import { parseQueryStatement } from '@/commands/query/lib/statement.ts';
import { queryListCommand } from '@/commands/query/list.ts';
import { queryShowCommand } from '@/commands/query/show.ts';
import { queryTopCommand } from '@/commands/query/top.ts';
import { optionalStringArg } from '@/lib/args.ts';
import { defineCommand } from '@/lib/command.ts';
import { CliError } from '@/lib/errors.ts';
Expand Down Expand Up @@ -30,12 +31,14 @@ export const queryCommand = defineCommand({
'altertable query @report.sql --format csv --output results.csv',
'altertable query list',
'altertable query show <query-id>',
'altertable query top --watch',
],
},
args: queryRunArgs,
subcommands: {
list: queryListCommand,
show: queryShowCommand,
top: queryTopCommand,
cancel: queryCancelCommand,
},
async run({ args, rawArgs, execution, sink }) {
Expand Down
Loading
Loading