chmonitorTables
Inspect table storage, replication health, schema, dictionaries, and background data-movement across all databases.
The Tables feature answers storage and replication questions across every database — sizes, parts, replica health, pending DDL, Kafka consumers, and dictionaries — without writing any SQL.
| Routes | /tables, /tables-overview, /replicas, /replication-queue, /replicated-fetches, /readonly-tables, /dropped-tables, /dictionaries, /kafka-consumers, /distributed-ddl-queue |
| Feature id | tables |
| Default access | public |
| Requires auth | No (set CHM_FEATURE_TABLES_ACCESS=authenticated to gate) |
| System tables | system.tables, system.parts, system.replicas, system.replication_queue, system.replicated_fetches, system.dropped_tables, system.dictionaries, system.kafka_consumers, system.distributed_ddl_queue |
| ClickHouse grants | SELECT on the system tables above; OPTIMIZE TABLE grant for the optimize action |
What it does
The Tables feature answers storage and replication questions without writing any SQL:
- How large is each table, and how many parts does it have?
- Are any replicated tables lagging or in read-only mode?
- What DDL operations are pending across the cluster?
- Which Kafka consumers are behind or erroring?
- What dictionaries are loaded and how much memory do they use?
All pages are read-only except for the OPTIMIZE TABLE action on the tables list, which requires an extra grant.
Using it
Each question maps to a dedicated page.
| Page | Route | What it shows | System tables |
|---|---|---|---|
| Tables | /tables | Table list with engine, row count, size; OPTIMIZE action | system.tables, system.parts |
| Tables Overview | /tables-overview | Storage statistics per table: part counts, compressed/uncompressed sizes | system.parts |
| Table Replicas | /replicas | Replicated table health: is_leader, queue depth, absolute_delay, last fetch | system.replicas |
| Replication Queue | /replication-queue | Pending and in-progress replication tasks from Keeper/ZooKeeper | system.replication_queue |
| Replicated Fetches | /replicated-fetches | Currently executing background part downloads between replicas | system.replicated_fetches |
| Readonly Tables | /readonly-tables | Tables whose replica is in read-only mode; filtered view of replicas | system.replicas |
| Dropped Tables | /dropped-tables | Tables awaiting async drop (Atomic database engine) | system.dropped_tables |
| Dictionaries | /dictionaries | External dictionary status, source type, memory usage | system.dictionaries |
| Kafka Consumers | /kafka-consumers | Kafka table engine consumer lag, poll/commit counts, ingestion errors | system.kafka_consumers |
| DDL Queue | /distributed-ddl-queue | Cluster-wide DDL task queue status and execution history | system.distributed_ddl_queue |
OPTIMIZE TABLE privilege required
The Tables page can issue OPTIMIZE TABLE. The ClickHouse user must have ALTER TABLE ... OPTIMIZE (or broader ALTER) privilege. Without it the action returns an error.
Optional and environment-dependent tables
Several pages are only relevant in specific configurations and show an informational empty state when their backing table is absent.
| Page | Condition |
|---|---|
| Kafka Consumers | Requires at least one Kafka table engine to be configured |
| Replicated Fetches | Only present on servers running replicated tables |
| Dropped Tables | Requires Atomic database engine (default since ClickHouse 20.6) |
| DDL Queue | Only meaningful on clusters using ON CLUSTER DDL |
- Readonly Tables — a replica enters read-only mode when it cannot reach Keeper/ZooKeeper. The
/readonly-tablespage is a filtered view ofsystem.replicas; it shows a zero-row table when all replicas are healthy.
Permissions & access
All sub-routes share the tables feature id:
CHM_FEATURE_TABLES_ACCESS=authenticated
# Disable entirely
CHM_FEATURE_TABLES_ENABLED=false
# or
CHM_DISABLED_FEATURES=tables# CHM_CONFIG_FILE (TOML)
[features.tables]
access = "authenticated"The Data Explorer (/explorer) is also under the tables feature id, so gating tables also gates the explorer.
There is no feature-specific configuration. The global query timeout applies to all table queries:
CLICKHOUSE_MAX_EXECUTION_TIME=60