chmonitorAI Agent
Capabilities
Full reference for the agent's 29+ tools, 18 expert skills, plan-and-verify mode, and worked example questions.
The agent exposes a small set of powerful primitives (29 tools, plus 3 env-gated control tools and 4 env-gated cross-source Postgres tools). Anything without a dedicated tool is done by writing SQL with the query tool, guided by a skill recipe. You never call tools directly — the agent picks and chains them automatically.
Tools
| Category | What it covers | Tools |
|---|---|---|
| Schema & exploration | Databases, tables, columns, ad-hoc SQL | query, list_databases, list_tables, get_table_schema, explore_table_schema |
| Query analysis | Running, slow, failed queries; normalized slow patterns; EXPLAIN; pre-flight cost estimate | get_running_queries, get_slow_queries, list_slow_query_patterns, get_failed_queries, explain_query, estimate_query_cost |
| Health, storage, replication, merges | Metrics, disks, parts, replication, merges | get_metrics, get_disk_usage, get_table_parts, get_replication_status, get_merge_status |
| Capacity planning | Disk-full forecast, TTL/retention advice, mutation impact dry-run (all recommend-only) | forecast_disk_capacity, suggest_ttl_adjustment, estimate_mutation_impact |
| Aggregation advisor | Design MV/projection DDL from frequent aggregation queries, with a size estimate (recommend-only) | recommend_materialized_view |
| Plan & verify | A visible, adaptive step-by-step plan | update_plan |
| Knowledge & interaction | Load expert guides; ask the user | load_skill, ask_user |
| Charts & visualization | Run SQL and return an interactive chart | query_and_visualize |
| Insights | Explain a statistical anomaly baseline and z-score | explain_anomaly_score |
| Reports | Generate a weekly/monthly cluster health report to narrate (read-only) | generate_cluster_report |
| Advisor | Ranked skip-index/projection/partition/PREWHERE recommendations for a slow query (recommend-only) | get_optimization_recommendations |
| Fine-tune | Ranked schema lint + settings tuning findings for a database/table (recommend-only) | get_tuning_suggestions |
| Dashboards | Suggest a dashboard layout from registry charts for a natural-language request (recommend-only) | suggest_dashboard |
| Control actions (env-gated) | Kill query/mutation, optimize table | kill_query, kill_mutation, optimize_table |
| Cross-source Postgres (env-gated) | Read-only SELECT, health metrics, slow-query patterns, and per-table stats against a Postgres source, for correlating with ClickHouse in one conversation | run_postgres_select_query, get_postgres_metrics, list_postgres_slow_query_patterns, get_postgres_table_stats |
Everything else (expensive-query rankings, query patterns, anomalies, table-design advice, settings, logs, replication queue, ZooKeeper, users…) is done with query plus the relevant skill recipe — so the agent keeps full reach with a much smaller, more reliable tool surface.
Control tools are off by default
Control tools (kill_query, kill_mutation, optimize_table) are disabled unless AGENT_ENABLE_CONTROL_TOOLS=true. The agent always confirms before using them.
Cross-source Postgres tools are off by default
The Postgres tools (run_postgres_select_query, get_postgres_metrics, list_postgres_slow_query_patterns, get_postgres_table_stats) appear only when CHM_FEATURE_POSTGRES_SOURCE=true and at least one Postgres source is configured via the POSTGRES_* env lists (see Configuration). They read Postgres over the read-only pg path and take a pgHostId (an index into the POSTGRES_* lists), so the agent can correlate ClickHouse and Postgres in one conversation. They read env-configured Postgres hosts; per-user (D1) Postgres connections are not yet visible to the agent — the same limitation as the ClickHouse agent tools.
Tool reference
| Tool | Description | Notes |
|---|---|---|
query | Execute a read-only SQL query on ClickHouse. | SELECT / WITH / DESCRIBE / EXPLAIN only. Write statements are rejected. Results are capped at 1000 rows (truncated: true + a note when hit) — add your own LIMIT or aggregation for larger result sets. |
list_databases | List all databases with engine and comment metadata. | |
list_tables | List tables in a database with row counts and size. | |
get_table_schema | Get column definitions for a specific table. | |
explore_table_schema | Three-mode exploration: no args → databases; database only → tables; database + table → full schema with indexes and keys. | |
get_running_queries | Currently running queries ordered by elapsed time. | Reads system.processes. |
get_slow_queries | Slowest completed queries from the query log. | Reads system.query_log. |
list_slow_query_patterns | Normalized slow query patterns — system.query_log grouped by normalized_query_hash, with calls, total/avg/p50/p95/p99/max duration, CPU time, peak memory, read/write bytes, errors, and cache-hit ratio per pattern. | Read-only. Use for "which query shape is expensive overall" — unlike get_slow_queries, which ranks individual executions. First step of the query-optimization diagnose loop. |
get_failed_queries | Recent failed queries with error details. | Reads system.query_log. |
explain_query | EXPLAIN PLAN / PIPELINE / PLAN with indexes for a query. | |
estimate_query_cost | Pre-flight cost estimate (rows scanned, bytes read, peak memory, wall time, confidence) from EXPLAIN alone. | Read-only and recommend-only — runs EXPLAIN only, never executes the analyzed query. |
get_metrics | Server health: version, uptime, active connections, memory. | Reads system.metrics. |
get_disk_usage | Per-disk free and total space. | Reads system.disks. |
get_table_parts | Part-level info for a table: rows, size, compression ratio. | Reads system.parts. |
forecast_disk_capacity | Forecast when disks will run out of free space from recent write-growth trend, plus top contributing tables. | Reads system.part_log (NewPart events) + system.disks. Reports a clear message instead of a forecast when part_log isn't enabled. |
suggest_ttl_adjustment | Recommend a TTL/retention change for a table to keep projected disk utilization ≤80%, never below a stated retention floor. | Returns a suggested ALTER TABLE ... MODIFY TTL ... string + risk note — recommend-only, never executed. Reports a clear message instead of a suggestion when part_log isn't enabled. |
estimate_mutation_impact | Pre-flight impact estimate for an ALTER TABLE ... UPDATE/DELETE: rows matched, parts/bytes to rewrite, projected duration from recent mutation throughput, and whether free disk can hold the rewrite. | Read-only and recommend-only — parses the statement as text and only ever runs derived read-only queries (SELECT count(), system.parts/part_log/disks); never executes the mutation. |
recommend_materialized_view | Mine frequent GROUP BY/aggregate query shapes and design a Summing/AggregatingMergeTree MV or projection to pre-aggregate them. | Returns DDL text + size estimate + impact + risk (added write-path/storage cost) — recommend-only, never executed. Reads system.query_log, system.parts, system.tables. |
get_replication_status | Per-table replication delay, queue size, and replica counts. | Reads system.replicas. |
get_merge_status | Currently running merges with progress and elapsed time. | Reads system.merges. |
update_plan | Create or update a step-by-step workflow plan for the current investigation. | Rendered as a live checklist in the UI. |
load_skill | Load an expert guide (skill) with SQL recipes for a specific domain. | |
find_reference_query | Search the dashboard's built-in library of 100+ vetted, version-aware monitoring queries and return the closest matches (name, description, SQL). | Read-only, deterministic keyword-overlap lookup over the built-in QueryConfig catalog — executes nothing. Meant to be used before hand-writing system.* SQL. |
ask_user | Ask the user a question to gather information before proceeding. | |
query_and_visualize | Run a SQL query and return an interactive chart config. | Chart type is auto-detected from result columns. Rows are capped at 1000 (truncated: true + a note when hit) before the chart is built. |
explain_anomaly_score | Explain a per-host/per-metric statistical anomaly baseline (mean, stddev, median, MAD, sample count) and, given a value, its z-score and anomaly verdict. | Read-only. Reports "no baseline yet" during cold start (falls back to a static threshold). |
generate_cluster_report | Generate a cluster health report (top insight findings, severity/category breakdown, baselines count, disk-capacity outlook) over a weekly (7-day) or monthly (30-day) window, returned as structured summary + markdown for the agent to narrate. | Read-only — same deterministic builder the scheduled reports use; scheduling and delivery are configured in /report-settings. |
get_optimization_recommendations | Analyze a slow query (by queryId from system.query_log, or raw sql) and return ranked skip-index, projection, partition-key, and PREWHERE recommendations with DDL/rewrite text, rationale, risk, effort, and an estimated granules/bytes saved. | Read-only and recommend-only — reads EXPLAIN + system.tables/system.columns/system.data_skipping_indexes/system.parts; never executes or applies any DDL or rewrite. Every impact figure is explicitly labeled an estimate. |
get_tuning_suggestions | Scan a database (or one table) for ranked schema lint findings — needless Nullable, oversized integers, compression-codec opportunities, LowCardinality candidates (ranked by on-disk bytes) — plus server/merge-tree settings that differ from defaults in risky ways. Each finding carries evidence (bytes/rows/ratios), an estimated benefit, ready-to-review DDL, and (for data-dependent rules) a verification query. | Read-only and recommend-only — reads system.columns/system.parts/system.settings/system.merge_tree_settings only (no user-table data); never executes or applies any DDL or settings change. Every benefit figure is explicitly labeled an estimate. |
suggest_dashboard | Map a natural-language request to a dashboard layout built only from charts in the chart registry, auto-placed on the plan-57 12-column grid. | Recommend-only — never persists anything. The chat UI shows an "Apply to dashboard" action that loads the layout into the dashboard builder's unsaved working grid; saving still requires the existing save action. Rejects any chart name not present in both the client and API chart registries. |
kill_query | Kill a running query by query_id. | DESTRUCTIVE. Env-gated: requires AGENT_ENABLE_CONTROL_TOOLS=true. Agent always confirms first. |
kill_mutation | Cancel a running mutation on a table. | DESTRUCTIVE. Env-gated: requires AGENT_ENABLE_CONTROL_TOOLS=true. Agent always confirms first. |
optimize_table | Trigger an OPTIMIZE on a table to force merges. | DESTRUCTIVE. Env-gated: requires AGENT_ENABLE_CONTROL_TOOLS=true. Agent always confirms first. |
run_postgres_select_query | Execute a read-only SQL query against a Postgres source (pgHostId). | Env-gated: requires CHM_FEATURE_POSTGRES_SOURCE=true. SELECT / WITH / SHOW / EXPLAIN / TABLE / VALUES only — writes and multi-statement strings are rejected and the session is pinned read-only. Results capped (default 1000 rows) with a truncated flag + note. |
get_postgres_metrics | Postgres health for a source (pgHostId): version, uptime, connection counts by state with max_connections + saturation %, buffer-cache hit ratio, transaction commit/rollback + deadlocks, database size, and replication status. | Env-gated: requires CHM_FEATURE_POSTGRES_SOURCE=true. Reads pg_stat_activity, pg_settings, pg_stat_database, pg_stat_replication. The Postgres analog of get_metrics. |
list_postgres_slow_query_patterns | Top normalized slow-query patterns from pg_stat_statements (pgHostId): calls, total/mean exec time, rows, shared-buffer cache-hit ratio, WAL bytes. | Env-gated: requires CHM_FEATURE_POSTGRES_SOURCE=true. Returns an informative message (not an error) when the pg_stat_statements extension is not installed. The Postgres analog of list_slow_query_patterns. |
get_postgres_table_stats | Per-table health for a source (pgHostId): worst dead-tuple bloat (dead vs live, dead %, last vacuum/autovacuum/analyze) and unused indexes (idx_scan = 0, excluding PK/unique, with on-disk size). | Env-gated: requires CHM_FEATURE_POSTGRES_SOURCE=true. Reads pg_stat_user_tables, pg_stat_user_indexes, pg_index. The per-table companion to get_postgres_metrics. |
Skills
Skills are expert guides — with copy-pasteable SQL recipes against system.* — that the agent loads on demand. Because the toolset is lean, skills are how the agent stays powerful. Eighteen skills are included:
| Skill | Covers |
|---|---|
system-tables-reference | Exact columns of key system tables; recipes; tools vs raw SQL |
data-analysis | Aggregation & time-series recipes (largest scan, expensive queries, patterns, period comparison) |
anomaly-detection | Recent-vs-baseline comparisons (error spikes, p95 regressions, part explosions) |
query-tuning-advisor | Diagnose a slow query and propose concrete rewrites & better joins |
query-optimization | PREWHERE, JOIN patterns, materialized views, EXPLAIN, indexes |
schema-design-advisor | ORDER BY/partition keys, codecs, skip indexes, column type right-sizing |
storage-optimization | Compression codecs, TTL, tiered storage, part management |
version-upgrade-advisor | Whether/how to upgrade ClickHouse and what is gained |
hardware-tuning | Size settings to the box's cores/RAM/disk |
concept-explainer | Teach core ClickHouse concepts |
replication-guide | ReplicatedMergeTree, failover, lag diagnosis, Keeper |
cluster-operations | Distributed tables, resharding, node management, topology |
migration-patterns | ALTER patterns, zero-downtime schema changes |
security-hardening | RBAC, row policies, quotas, audit logging |
clickhouse-best-practices | Schema design, query tuning, operational guidelines |
troubleshooting | OOM, slow merges, stuck mutations, error-code diagnosis |
incident-response | Structured triage recipes (disk full, errors, replication lag, health sweep) |
plan-and-verify | Decompose with update_plan and verify each result before concluding |
List available skills with GET /api/v1/agent/skills.
Plan and verify
For multi-step tasks the agent authors a live checklist with update_plan, keeps exactly one step in progress, and adapts the plan as results come in. Crucially, it verifies each result before stating it — re-querying or cross-checking a second system table for a finding, running explain_query on both versions before claiming a rewrite is faster, and separating what is verified from what is a hypothesis. The plan-and-verify and incident-response skills encode the recipes. Simple one-step questions skip the plan entirely.
Example questions
Ask in plain English:
- "Which queries are running right now and how long have they been executing?" — lists query id, user, elapsed time, and memory, sorted by duration.
- "What were the 10 slowest queries in the last 24 hours?" — fetches from the query log and offers to EXPLAIN any of them.
- "What's the largest data scan ever performed on this cluster?" — loads
data-analysisand runs thesystem.query_logrecipe. - "Anything abnormal in the last hour versus baseline?" — loads
anomaly-detectionand compares recent activity to the preceding window. - "Show me query volume per hour over the last day as a chart." — runs the aggregation and renders a line chart inline.
- "Suggest a better ORDER BY and which columns should be LowCardinality for
analytics.events." — loadsschema-design-advisor, inspects the schema and parts, and recommends changes.
Related
AI Agent
Overview of the agent, its architecture, and quick start.
Configuration
All environment variables, LLM providers, and access control.
Conversation history
How chat history works and how to enable server-side persistence.
ClickHouse query optimization
The diagnose loop above, explained end to end with runnable SQL.