# Queries

> Monitor and analyze all query activity: live execution, historical logs, failures, resource cost, thread-level breakdown, and per-user process summaries.

| | |
|---|---|
| **Routes** | `/running-queries`, `/history-queries`, `/failed-queries`, `/expensive-queries`, `/slow-queries`, `/explain`, `/query-views-log`, `/queries/thread-analysis`, `/user-processes`, `/query-metric-log` |
| **Feature id** | `queries` |
| **Default access** | `public` |
| **Requires auth** | No (set `CHM_FEATURE_QUERIES_ACCESS=authenticated` to gate) |
| **System tables** | `system.processes`, `system.query_log`, `system.query_views_log`, `system.query_thread_log`, `system.user_processes`, `system.query_metric_log`, `system.errors` |
| **ClickHouse grants** | `SELECT` on the system tables above; `KILL QUERY` for the kill-query action |

## What it does

The Queries feature covers the full lifecycle of query observability:

- **Live** — what is running right now, elapsed time, memory, thread count.
- **History** — finished queries with full metrics (CPU, memory, read/write rows and bytes, duration).
- **Failures** — queries that errored, with error codes and messages.
- **Cost** — top queries by CPU, duration, or memory over a selected time window.
- **Thread & parallelization** — per-thread breakdown of a single query execution.
- **Materialized view log** — how each materialized view was triggered and how long it took.
- **User processes** — aggregated per-user resource usage from live processes.
- **Query metric log** — per-query resource samples taken throughout a query's lifetime.

The Explain page does not query a log table; it runs `EXPLAIN` statements against the connected host interactively.

## Pages

| Page | Route | What it shows | System tables |
|---|---|---|---|
| Running Queries | `/running-queries` | Live query list: elapsed, memory, read rows, thread count; kill action | `system.processes` |
| History Queries | `/history-queries` | Finished queries with full metrics; filter by user, query type, time range | `system.query_log` |
| Failed Queries | `/failed-queries` | Queries that ended with an exception; error code and message | `system.query_log` |
| Most Expensive Queries | `/expensive-queries` | Top queries by CPU time, duration, or memory | `system.query_log` |
| Slow Queries | `/slow-queries` | Top 10 slowest finished queries by duration | `system.query_log` |
| Explain | `/explain` | Interactive EXPLAIN for any SQL; no log table queried | — |
| Query Views Log | `/query-views-log` | Materialized view execution history: status, duration, row throughput | `system.query_views_log` |
| Thread & Parallelization | `/queries/thread-analysis` | Thread-level performance breakdown for individual query executions | `system.query_thread_log` |
| User Processes | `/user-processes` | Per-user memory and resource summary from live processes | `system.user_processes` |
| Query Metric Log | `/query-metric-log` | Per-query resource timeline sampled over each query's lifetime | `system.query_metric_log` |

## Permissions & access

All query pages fall under the `queries` feature id:

```bash
## Gate the whole feature to authenticated users
CHM_FEATURE_QUERIES_ACCESS=authenticated

## Disable the whole feature
CHM_FEATURE_QUERIES_ENABLED=false
## or
CHM_DISABLED_FEATURES=queries
```

```toml
## CHM_CONFIG_FILE (TOML)
[features.queries]
access = "authenticated"
```

When disabled, all sub-routes are removed from the nav and return a disabled screen on direct visit.

## Configuration

No feature-specific configuration beyond the global query settings:

```bash
CLICKHOUSE_MAX_EXECUTION_TIME=60   # per-query timeout in seconds
```

## Notes & limitations

- **Kill action** — the kill-query button on `/running-queries` issues `KILL QUERY`. The ClickHouse user configured via `CLICKHOUSE_USER` must have the `KILL QUERY` privilege. Without it, the button returns an error.
- **`system.query_log`** — ClickHouse writes to `query_log` asynchronously. Very recent queries (< a few seconds old) may not appear in history pages yet. Log retention and flush intervals are controlled by ClickHouse server config (`query_log.flush_interval_milliseconds`, `query_log.ttl`), not by chmonitor.
- **`system.query_views_log`** — only populated if `<query_views_log>` is enabled in the ClickHouse server config. The page shows an empty state or a table-not-found notice if it is absent.
- **`system.query_thread_log`** — requires `<query_thread_log>` to be enabled in ClickHouse config. Disabled by default on many installations.
- **`system.user_processes`** — available since ClickHouse 22.6. Earlier versions will show a table-not-found notice.
- **`system.query_metric_log`** — requires `<query_metric_log>` to be enabled in ClickHouse config. High-cardinality on busy clusters; enable with care.
- **`system.errors`** — the Common Errors view reads `system.errors`, which is always present and contains aggregated error-code counts (not per-query).

## Related

- [Authentication](/authentication)
- [Settings reference](/settings)
- [Operations (merges & mutations)](/features/operations)