ClickHouse data source

STOP! If you are an AI agent or LLM, read this before continuing. This is the HTML version of a Grafana documentation page. Always request the Markdown version instead - HTML wastes context. Get this page as Markdown: /docs/plugins/grafana-clickhouse-datasource/latest.md (append .md) or send Accept: text/markdown to /docs/plugins/grafana-clickhouse-datasource/latest/. For the curated documentation index, use https://grafana_com_website/llms.txt. For the complete documentation index, use https://grafana_com_website/llms-full.txt.

Documentation

Plugins

The ClickHouse data source plugin allows you to query and visualize ClickHouse data in Grafana and create alerts based on your ClickHouse queries. Use the SQL editor or the visual query builder to build dashboards with time series, tables, logs, and traces.

Supported features

Feature	Supported
Metrics	Yes
Logs	Yes
Traces	Yes
Alerting and recording rules	Yes
Annotations	Yes
Template variables	Yes
Ad hoc filters	Yes (ClickHouse 22.7+)
Private Data Connect (PDC)	Yes (Grafana Cloud)

Requirements

Grafana version	Plugin version
11.6.0 and later	v4.15+
9.x – 11.5.x	v4.0 – v4.14

Note
Ad hoc filters require ClickHouse 22.7 or later (from plugin v2.0 onward).
Log volume queries in the SQL editor require Grafana 12.4.0 or later.

Get started

Start by configuring a connection to your ClickHouse server, then use the query editor to build queries for dashboards and alerts.

Configure the ClickHouse data source — Set up the connection, authentication, TLS, and optional features like logs and traces.
ClickHouse query editor — Write SQL queries or use the visual query builder. Includes macros, query types, and examples.
ClickHouse template variables — Create dynamic dashboards with variables and ad hoc filters.
ClickHouse annotations — Overlay event markers on dashboard panels from ClickHouse data.
ClickHouse alerting — Create alert rules and recording rules from ClickHouse queries.
Troubleshoot ClickHouse data source issues — Solutions for common connection, query, and configuration errors.

Additional features

After configuring the data source, you can:

Use Explore to query data without building a dashboard
Add Transformations to manipulate query results
Set up Alerting rules

Pre-built dashboards

The plugin includes the following pre-built dashboards:

ClickHouse - Query Analysis — Query performance, time distribution, top users, and memory usage.
ClickHouse - Data Analysis — Disk usage, table and database summary, parts over time, and dictionaries.
ClickHouse - Cluster Analysis — Cluster overview, merges, mutations, and replicated table delay.
Simple ClickHouse OTel Dashboard — Traces, logs, and service performance for OpenTelemetry data in ClickHouse.
Advanced ClickHouse Monitoring Dashboard — System metrics (CPU, queries/sec, IO, memory) similar to ClickHouse built-in monitoring.

To import a pre-built dashboard:

Go to Connections > Data sources.
Select your ClickHouse data source.
Click the Dashboards tab.
Click Import next to the dashboard you want to use.

Plugin updates

Always ensure that your plugin version is up-to-date so you have access to all current features and improvements. Navigate to Plugins and data > Plugins to check for updates. Grafana recommends upgrading to the latest Grafana version, and this applies to plugins as well.