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
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,14 @@ auto-generated per-PR notes; this file is the curated, human-readable history.

## [Unreleased]

### Changed
- Consolidated the non-Iceberg examples into three responsive flagship
dashboards: On-time flights, Shop analytics, and ClickHouse Operations.
Each uses an authored `grafana-grid@1` layout with a complete `flow@1`
fallback, shared filters, and focused visible tiles; useful secondary
analyses remain untiled Library entries. Removed the superseded KPI, logs,
query-log, System Explorer, and earlier Grafana-port fixtures and generator.

### Added
- **Cross-tab workspace consistency: refresh before write and stale-tab
invalidation** (#343). Workbench and editable-Dashboard tabs editing the same
Expand Down
41 changes: 21 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,20 @@ held at **100% test coverage**.

See the [**feature tour, deployment guide and screenshots**](https://docs.altinity.com/altinity-sql-browser/)
on the project site. Try it live on the Antalya demo cluster: **https://antalya.demo.altinity.cloud/sql**.
The [**ontime chart demo**](docs/ONTIME-CHART-DEMO.md) is a ready-made library of 10
queries (load [`examples/ontime-charts.json`](examples/ontime-charts.json) via
**File ▾ → Import queries**) that walks through every chart type and feature against the public
`ontime` flight dataset. The [**system explorer demo**](docs/SYSTEM-EXPLORER-DEMO.md)
is a 14-query library (load [`examples/system-explorer-charts.json`](examples/system-explorer-charts.json)
via **File ▾ → Import queries**) that introspects ClickHouse's own `system` database —
running queries, merges/replication health, and historical query/part/error
activity — with a shared From/To filter driving every time-ranged Dashboard tile
at once.
Three flagship bundles cover the main workflows without a pile of one-feature
fixtures:

- [**On-time flights**](docs/ONTIME-CHART-DEMO.md) — seven analytical tiles,
a KPI band, a shared 2023 date range, and carrier/airport multiselects over
the public `ontime` dataset.
- [**Shop analytics**](docs/SHOP-ANALYTICS-DEMO.md) — seven business tiles over
the schema, sample data, materialized views, and dictionary created by
[`examples/shop-demo.sql`](examples/shop-demo.sql).
- [**ClickHouse Operations**](docs/CLICKHOUSE-OPERATIONS-DEMO.md) — sixteen
operator-first tiles for live health, resources, background work, and
investigation, with the remaining operational queries kept in the Library.

Load the corresponding portable bundle from `examples/` with **File ▾ → Open…**.
The [**Iceberg catalog explorer**](docs/ICEBERG-CATALOG-EXPLORER-DEMO.md) is a
distributable installer + two dashboards for Iceberg data-lake catalogs:
[`examples/iceberg-install.json`](examples/iceberg-install.json) generates the
Expand Down Expand Up @@ -92,9 +97,9 @@ ordinary `.kpi-panel` grid, while a **favorited, explicitly-KPI-typed** Dashboar
query instead joins a full-width **KPI band** — a flat, wrapping card stream
with no per-favorite name, description, or statistics footer, spanning every
flow Dashboard layout (Report/2/3 columns). Consecutive explicit KPI
favorites merge into one shared band. The complete
[`kpi-panel.json`](examples/kpi-panel.json) Library example can be opened from
**File ▾ → Import queries** to see both.
favorites merge into one shared band. The On-time, Shop, and Operations
flagship dashboards all include a production
KPI band alongside charts, tables, and logs.
When constructing a named tuple from expressions, either enable alias-derived
member names for the query:

Expand Down Expand Up @@ -492,14 +497,10 @@ nested option values, limits each helper to 1,000 options, and falls back to the
ordinary parameter field when a source, consumer type, or provider conflicts.
Filter sources run and reconcile saved values before any Panel query starts.

The complete [`query-log-explorer.json`](examples/query-log-explorer.json)
Library example (load via **File ▾ → Import queries**) demonstrates every filter
variant against `system.query_log` on any cluster: three Filter sources, one
per option shape (`Array(Tuple(value, label))`, `Map(String, String)`, plain
`Array(T)`), alongside plain auto-detected numeric/text fields — a KPI panel,
four analytical Panels adapted from the Altinity KB's ["Handy queries for
system.query_log"](https://kb.altinity.com/altinity-kb-useful-queries/query_log/),
a Logs panel, and a Text panel explaining the demo.
The flagship bundles demonstrate the same contracts in context: readable
`Array(Tuple(value, label))` airport options in On-time, targeted country and
category filters in Shop, and inferred `Array(T)` multiselects for operational
query-log dimensions in ClickHouse Operations.

```sql
SELECT
Expand Down
27 changes: 27 additions & 0 deletions docs/CLICKHOUSE-OPERATIONS-DEMO.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# ClickHouse Operations dashboard

[`examples/clickhouse-operations.json`](../examples/clickhouse-operations.json)
is an operator-first dashboard imported and curated from the ClickHouse
Operations bundle. Open it with **File ▾ → Open…** against a cluster where the
signed-in user can inspect the relevant `system` tables.

Its sixteen visible tiles follow an investigation path:

- overview: live KPIs, running queries, query rate, active connections;
- resources: CPU, memory, I/O utilization, network traffic;
- background work: merges, mutations, replication checks;
- investigation: errors, largest tables, query-hash metric, query details, and
recent server logs.

The active time range defaults to `-1h` through `now`. `user`, `query_kind`,
`exception_code`, and `query_hash` are inferred searchable multiselects; their
consumers consistently use `Array(T)` parameters with `has(...)`. `metric` and
`is_initial_query` remain single-select controls, while time and log search are
scalar. The other downloaded operational queries remain untiled in the Library.

Typical grants include `SELECT` on `system.metric_log`,
`system.asynchronous_metric_log`, `system.query_log`, `system.part_log`,
`system.text_log`, `system.parts`, `system.merges`, `system.mutations`, and
replication-related system tables. Exact availability depends on server
version and deployment policy; missing grants fail individual tiles without
hiding the rest of the dashboard.
80 changes: 21 additions & 59 deletions docs/ONTIME-CHART-DEMO.md
Original file line number Diff line number Diff line change
@@ -1,65 +1,27 @@
# Chart demo — the `ontime` flight dataset
# On-time flights dashboard

A ready-made **Library** of 10 analytical queries that show off every chart type and
feature in the Altinity® SQL Browser, running against the public US flight-history
dataset (`ontime`, ~230M rows, 1987–2025) on the Antalya demo cluster.
[`examples/ontime-charts.json`](../examples/ontime-charts.json) is the flagship
analytical dashboard for the public `ontime` flight dataset. Open it on the
[Antalya demo](https://antalya.demo.altinity.cloud/sql) with **File ▾ → Open…**.

- **Live demo:** **https://antalya.demo.altinity.cloud/sql**
- **The library file:** [`examples/ontime-charts.json`](../examples/ontime-charts.json)
([raw download](https://raw.githubusercontent.com/Altinity/altinity-sql-browser/main/examples/ontime-charts.json))
- **Reproduce it:** [`examples/mjs/build-ontime-charts.mjs`](../examples/mjs/build-ontime-charts.mjs)
regenerates the JSON (it derives each chart's schema key live with
`clickhouse-client --connection antalya`).
The authored grid contains seven visible tiles: Flight KPIs, Daily flights,
On-time rate, Busiest origins, Monthly carrier volume, Delay causes by carrier,
and Cancellation reasons. Additional chart analyses remain available as
untiled Library entries.

## Load it (≈30 seconds)
The active time range defaults to `2023-01-01` through `2023-12-31`. Carrier
and Origin airport start inactive and become searchable multiselects because
every targeted query declares `Array(String)` and uses `has(...)`. Airport
codes are the bound values; readable airport names are the labels.

1. Open **https://antalya.demo.altinity.cloud/sql** and sign in (**Continue with Google**,
or use the credentials box).
2. Download [`ontime-charts.json`](https://raw.githubusercontent.com/Altinity/altinity-sql-browser/main/examples/ontime-charts.json)
(right-click → Save link as…).
3. In the header, click **File ▾ → Open…** and pick the file. The library is renamed
**ontime-charts** and fills with 10 saved queries (confirm the replace if you already
had queries saved).
4. Click any query in the **Queries** panel — it runs and opens straight into its chart.
Switch **Table / JSON / Chart** at the top of the results, or change the **Type / X / Y /
Series** dropdowns to re-encode any chart live.
The dashboard reads `ontime.fact_ontime` and joins
`ontime.dim_airports` for origin names. To refresh panel schema keys against
the configured connection, run:

## What each query demonstrates
```bash
node examples/mjs/build-ontime-charts.mjs
```

| # | Query | Chart | Feature |
|---|-------|-------|---------|
| 1 | Busiest origin airports — 2023 | Bar (horizontal) | categorical axis; joined to `dim_airports` for readable names; hover any bar (long or short) for its exact value |
| 2 | Flights by month — 2023 | Column | numeric `month` auto-detected as an ordinal axis; K/M-humanised value ticks |
| 3 | Daily flights — 2023 | Line | `Date` axis auto-detected as a time series (~365 points) |
| 4 | Daily on-time rate — 2023 | Area | filled time series (a percentage measure) |
| 5 | Cancellation reasons — 2023 | Pie | share of a small category set, with a legend |
| 6 | Monthly flights by carrier — 2023 | Grouped bars | a **Series** column (carrier) splits each month into per-carrier bars |
| 7 | Average delay breakdown by carrier — 2023 | Multi-measure columns | four measures plotted together (“All measures”) |
| 8 | Daily flights since 2022 | Line | result exceeds the chart cap → a **“first 500 of 1.5K rows”** note (the table keeps them all) |
| 9 | Flights by day of week — 2023 | Column | ordinal `dayofweek` axis |
| 10 | Worst average departure delay by airport — 2023 | Bar (horizontal) | a non-count measure (avg minutes), joined for names |

Each saved query stores its panel configuration in the complete query Spec, so it reopens exactly as designed. (Charts
plot the first 500 rows; the full result is always available in the Table view.)

## Direct links

Every query is also reachable as a single shareable link — open one and the SQL **and** its
chart configuration are pre-loaded; press **Run**, then the **Chart** tab. (Inside the app,
the **Share** button copies the same kind of link for whatever you're looking at.)

- **Bar** — [Busiest origin airports — 2023](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUXG4gICAgYS5EaXNwbGF5QWlycG9ydE5hbWUgQVMgYWlycG9ydCxcbiAgICBjb3VudCgpIEFTIGZsaWdodHNcbkZST00gb250aW1lLmZhY3Rfb250aW1lIEFTIGZcbklOTkVSIEpPSU4gb250aW1lLmRpbV9haXJwb3J0cyBBUyBhXG4gICAgT04gYS5BaXJwb3J0Q29kZSA9IGYuT3JpZ2luQ29kZSBBTkQgYS5Jc0xhdGVzdCA9IDFcbldIRVJFIGYuWWVhciA9IDIwMjNcbkdST1VQIEJZIGFpcnBvcnRcbk9SREVSIEJZIGZsaWdodHMgREVTQ1xuTElNSVQgMTUiLCJjaGFydCI6eyJjZmciOnsidHlwZSI6ImhiYXIiLCJ4IjowLCJ5IjpbMV0sInNlcmllcyI6bnVsbH0sImtleSI6ImFpcnBvcnQ6U3RyaW5nfGZsaWdodHM6VUludDY0In19)
- **Column** — [Flights by month — 2023](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUIE1vbnRoIEFTIG1vbnRoLCBjb3VudCgpIEFTIGZsaWdodHNcbkZST00gb250aW1lLmZhY3Rfb250aW1lXG5XSEVSRSBZZWFyID0gMjAyM1xuR1JPVVAgQlkgbW9udGhcbk9SREVSIEJZIG1vbnRoIiwiY2hhcnQiOnsiY2ZnIjp7InR5cGUiOiJiYXIiLCJ4IjowLCJ5IjpbMV0sInNlcmllcyI6bnVsbH0sImtleSI6Im1vbnRoOlVJbnQ4fGZsaWdodHM6VUludDY0In19)
- **Line** — [Daily flights — 2023](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUIEZsaWdodERhdGUgQVMgZGF0ZSwgY291bnQoKSBBUyBmbGlnaHRzXG5GUk9NIG9udGltZS5mYWN0X29udGltZVxuV0hFUkUgWWVhciA9IDIwMjNcbkdST1VQIEJZIGRhdGVcbk9SREVSIEJZIGRhdGUiLCJjaGFydCI6eyJjZmciOnsidHlwZSI6ImxpbmUiLCJ4IjowLCJ5IjpbMV0sInNlcmllcyI6bnVsbH0sImtleSI6ImRhdGU6RGF0ZXxmbGlnaHRzOlVJbnQ2NCJ9fQ==)
- **Area** — [Daily on-time rate — 2023](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUXG4gICAgRmxpZ2h0RGF0ZSBBUyBkYXRlLFxuICAgIHJvdW5kKDEwMCAqIGNvdW50SWYoQXJyRGVsMTUgPSAwKSAvIGNvdW50KCksIDEpIEFTIG9uX3RpbWVfcGN0XG5GUk9NIG9udGltZS5mYWN0X29udGltZVxuV0hFUkUgWWVhciA9IDIwMjNcbkdST1VQIEJZIGRhdGVcbk9SREVSIEJZIGRhdGUiLCJjaGFydCI6eyJjZmciOnsidHlwZSI6ImFyZWEiLCJ4IjowLCJ5IjpbMV0sInNlcmllcyI6bnVsbH0sImtleSI6ImRhdGU6RGF0ZXxvbl90aW1lX3BjdDpGbG9hdDY0In19)
- **Pie** — [Cancellation reasons — 2023](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUXG4gICAgbXVsdGlJZihDYW5jZWxsYXRpb25Db2RlID0gJ0EnLCAnQ2FycmllcicsXG4gICAgICAgICAgICBDYW5jZWxsYXRpb25Db2RlID0gJ0InLCAnV2VhdGhlcicsXG4gICAgICAgICAgICBDYW5jZWxsYXRpb25Db2RlID0gJ0MnLCAnTmF0aW9uYWwgQWlyIFN5c3RlbScsXG4gICAgICAgICAgICBDYW5jZWxsYXRpb25Db2RlID0gJ0QnLCAnU2VjdXJpdHknLCAnT3RoZXInKSBBUyByZWFzb24sXG4gICAgY291bnQoKSBBUyBjYW5jZWxsYXRpb25zXG5GUk9NIG9udGltZS5mYWN0X29udGltZVxuV0hFUkUgWWVhciA9IDIwMjMgQU5EIENhbmNlbGxlZCA9IDFcbkdST1VQIEJZIHJlYXNvblxuT1JERVIgQlkgY2FuY2VsbGF0aW9ucyBERVNDIiwiY2hhcnQiOnsiY2ZnIjp7InR5cGUiOiJwaWUiLCJ4IjowLCJ5IjpbMV0sInNlcmllcyI6bnVsbH0sImtleSI6InJlYXNvbjpTdHJpbmd8Y2FuY2VsbGF0aW9uczpVSW50NjQifX0=)
- **Grouped columns** — [Monthly flights by carrier — 2023](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUXG4gICAgTW9udGggQVMgbW9udGgsXG4gICAgQ2FycmllciBBUyBjYXJyaWVyLFxuICAgIGNvdW50KCkgQVMgZmxpZ2h0c1xuRlJPTSBvbnRpbWUuZmFjdF9vbnRpbWVcbldIRVJFIFllYXIgPSAyMDIzIEFORCBDYXJyaWVyIElOICgnV04nLCAnQUEnLCAnREwnLCAnVUEnKVxuR1JPVVAgQlkgbW9udGgsIGNhcnJpZXJcbk9SREVSIEJZIG1vbnRoLCBjYXJyaWVyIiwiY2hhcnQiOnsiY2ZnIjp7InR5cGUiOiJiYXIiLCJ4IjowLCJ5IjpbMl0sInNlcmllcyI6MX0sImtleSI6Im1vbnRoOlVJbnQ4fGNhcnJpZXI6TG93Q2FyZGluYWxpdHkoU3RyaW5nKXxmbGlnaHRzOlVJbnQ2NCJ9fQ==)
- **Multi-measure columns** — [Average delay breakdown by carrier — 2023](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUXG4gICAgQ2FycmllciBBUyBjYXJyaWVyLFxuICAgIHJvdW5kKGF2ZyhDYXJyaWVyRGVsYXkpLCAxKSBBUyBjYXJyaWVyX2RlbGF5LFxuICAgIHJvdW5kKGF2ZyhXZWF0aGVyRGVsYXkpLCAxKSBBUyB3ZWF0aGVyX2RlbGF5LFxuICAgIHJvdW5kKGF2ZyhOQVNEZWxheSksIDEpIEFTIG5hc19kZWxheSxcbiAgICByb3VuZChhdmcoTGF0ZUFpcmNyYWZ0RGVsYXkpLCAxKSBBUyBsYXRlX2FpcmNyYWZ0X2RlbGF5XG5GUk9NIG9udGltZS5mYWN0X29udGltZVxuV0hFUkUgWWVhciA9IDIwMjMgQU5EIEFyckRlbDE1ID0gMVxuR1JPVVAgQlkgY2FycmllclxuT1JERVIgQlkgY2Fycmllcl9kZWxheSBERVNDXG5MSU1JVCAxMiIsImNoYXJ0Ijp7ImNmZyI6eyJ0eXBlIjoiYmFyIiwieCI6MCwieSI6WzEsMiwzLDRdLCJzZXJpZXMiOm51bGx9LCJrZXkiOiJjYXJyaWVyOkxvd0NhcmRpbmFsaXR5KFN0cmluZyl8Y2Fycmllcl9kZWxheTpOdWxsYWJsZShGbG9hdDY0KXx3ZWF0aGVyX2RlbGF5Ok51bGxhYmxlKEZsb2F0NjQpfG5hc19kZWxheTpOdWxsYWJsZShGbG9hdDY0KXxsYXRlX2FpcmNyYWZ0X2RlbGF5Ok51bGxhYmxlKEZsb2F0NjQpIn19)
- **Line (capped)** — [Daily flights since 2022](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUIEZsaWdodERhdGUgQVMgZGF0ZSwgY291bnQoKSBBUyBmbGlnaHRzXG5GUk9NIG9udGltZS5mYWN0X29udGltZVxuV0hFUkUgRmxpZ2h0RGF0ZSA+PSAnMjAyMi0wMS0wMSdcbkdST1VQIEJZIGRhdGVcbk9SREVSIEJZIGRhdGUiLCJjaGFydCI6eyJjZmciOnsidHlwZSI6ImxpbmUiLCJ4IjowLCJ5IjpbMV0sInNlcmllcyI6bnVsbH0sImtleSI6ImRhdGU6RGF0ZXxmbGlnaHRzOlVJbnQ2NCJ9fQ==)
- **Column** — [Flights by day of week — 2023](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUIERheU9mV2VlayBBUyBkYXlvZndlZWssIGNvdW50KCkgQVMgZmxpZ2h0c1xuRlJPTSBvbnRpbWUuZmFjdF9vbnRpbWVcbldIRVJFIFllYXIgPSAyMDIzXG5HUk9VUCBCWSBkYXlvZndlZWtcbk9SREVSIEJZIGRheW9md2VlayIsImNoYXJ0Ijp7ImNmZyI6eyJ0eXBlIjoiYmFyIiwieCI6MCwieSI6WzFdLCJzZXJpZXMiOm51bGx9LCJrZXkiOiJkYXlvZndlZWs6VUludDh8ZmxpZ2h0czpVSW50NjQifX0=)
- **Bar** — [Worst average departure delay by airport — 2023](https://antalya.demo.altinity.cloud/sql#eyJfX2FzYiI6MSwic3FsIjoiU0VMRUNUXG4gICAgYS5EaXNwbGF5QWlycG9ydE5hbWUgQVMgYWlycG9ydCxcbiAgICByb3VuZChhdmcoZi5EZXBEZWxheU1pbnV0ZXMpLCAxKSBBUyBhdmdfZGVwX2RlbGF5XG5GUk9NIG9udGltZS5mYWN0X29udGltZSBBUyBmXG5JTk5FUiBKT0lOIG9udGltZS5kaW1fYWlycG9ydHMgQVMgYVxuICAgIE9OIGEuQWlycG9ydENvZGUgPSBmLk9yaWdpbkNvZGUgQU5EIGEuSXNMYXRlc3QgPSAxXG5XSEVSRSBmLlllYXIgPSAyMDIzXG5HUk9VUCBCWSBhaXJwb3J0XG5IQVZJTkcgY291bnQoKSA+PSAxMDAwMFxuT1JERVIgQlkgYXZnX2RlcF9kZWxheSBERVNDXG5MSU1JVCAxNSIsImNoYXJ0Ijp7ImNmZyI6eyJ0eXBlIjoiaGJhciIsIngiOjAsInkiOlsxXSwic2VyaWVzIjpudWxsfSwia2V5IjoiYWlycG9ydDpTdHJpbmd8YXZnX2RlcF9kZWxheTpOdWxsYWJsZShGbG9hdDY0KSJ9fQ==)

## Tables used

- `ontime.fact_ontime` — one row per US domestic flight (dates, carrier, origin/dest, delays, cancellations, …).
- `ontime.dim_airports` — airport reference data; joined on `AirportCode = OriginCode AND IsLatest = 1` for human-readable airport names.
The generator preserves the authored tile order and sizes, filters and
defaults, KPI field configuration, semantic dashboard identity, and complete
`flow@1` fallback.
23 changes: 23 additions & 0 deletions docs/SHOP-ANALYTICS-DEMO.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Shop analytics dashboard

The Shop example has two deliberately separate artifacts:

- [`examples/shop-demo.sql`](../examples/shop-demo.sql) creates the `shop`
schema, sample events/products, dictionary, materialized views, aggregate
tables, and lineage relationships.
- [`examples/shop-charts.json`](../examples/shop-charts.json) contains the
reusable queries and authored dashboard, without duplicating setup SQL.

Load the SQL once with a suitably privileged ClickHouse client, then open the
bundle with **File ▾ → Open…**. The dashboard shows Sales KPIs, Daily revenue,
Revenue by country, Revenue by category, Top products, Daily active users, and
Traffic by hour. Country revenue trends remain as an untiled Library analysis.

The active range defaults to `-90d` through `now`. Country and Category are
inactive searchable multiselects. Their target lists are explicit because the
aggregate tables intentionally do not all carry both dimensions.

The setup user needs create/insert privileges for `shop.*`. Dashboard users
need `SELECT ON shop.*`; `SELECT ON system.dictionaries` is also required to
show dictionary lineage. The dictionary's ClickHouse source user must be able
to read `shop.products`.
Loading