system-tables-reference

What problem does it solve?

Writing raw SQL against ClickHouse system tables frequently causes errors from referencing non-existent (hallucinated) columns, wastes time debugging failed queries, and produces incorrect results when users guess column names or use outdated schema information. It also creates unnecessary work when pre-built, version-aware dedicated tools exist for common monitoring and troubleshooting tasks.

Core Features & Use Cases

• Verified Column Reference: Provides exact, up-to-date column names for all commonly queried ClickHouse system tables (including processes, query_log, parts, merges, mutations, replicas, replication_queue, disks, settings, zookeeper, users/grants, metrics, and more) to eliminate guesswork and avoid unknown column errors.
• Tool Mapping Guide: Maps routine monitoring questions (for example, "what queries are running now?" or "what are the slowest finished queries?") to their corresponding pre-built dedicated tools, so users do not have to write or maintain raw SQL for standard operational tasks.
• Edge Case Rules: Includes critical schema quirks and usage rules, such as the lack of a database column on system.processes (use current_database instead), the required path filter for system.zookeeper, and the need to filter type = 'QueryFinish' on system.query_log to avoid double-counting completed queries.
• Use Case: A DBA troubleshooting a replication lag issue can use this skill to quickly confirm the correct columns for system.replicas and use the dedicated get_replication_status tool instead of writing a custom raw SQL query that may miss key fields or return incorrect results.

Quick Start

Use the system-tables-reference skill to verify the correct column names for the system.replicas table before writing a query to check for replication lag across your ClickHouse cluster.