--- title: "ClickHouse data source | Grafana Plugins documentation" description: "This document introduces the ClickHouse data source" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # ClickHouse data source 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 Expand table | 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 Expand table | 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 fall back to Grafana’s row-based histogram on Grafana 12.4.0 and later. On earlier versions a query the plugin cannot aggregate shows no volume chart. ## Get started Start by configuring a connection to your ClickHouse server, then use the query editor to build queries for dashboards and alerts. 1. [Configure the ClickHouse data source](/docs/plugins/grafana-clickhouse-datasource/latest/configure/): Set up the connection, authentication, TLS, and optional features like logs and traces. 2. [ClickHouse query editor](/docs/plugins/grafana-clickhouse-datasource/latest/query-editor/): Write SQL queries or use the visual query builder. Includes macros, query types, and examples. 3. [ClickHouse template variables](/docs/plugins/grafana-clickhouse-datasource/latest/template-variables/): Create dynamic dashboards with variables and ad hoc filters. 4. [ClickHouse annotations](/docs/plugins/grafana-clickhouse-datasource/latest/annotations/): Overlay event markers on dashboard panels from ClickHouse data. 5. [ClickHouse alerting](/docs/plugins/grafana-clickhouse-datasource/latest/alerting/): Create alert rules and recording rules from ClickHouse queries. 6. [Troubleshoot ClickHouse data source issues](/docs/plugins/grafana-clickhouse-datasource/latest/troubleshooting/): Solutions for common connection, query, and configuration errors. ## Additional features After configuring the data source, you can: - Use [Explore](/docs/grafana/latest/explore/) to query data without building a dashboard - Add [Transformations](/docs/grafana/latest/panels/transformations/) to manipulate query results - Set up [Alerting](/docs/grafana/latest/alerting/) rules ## Pre-built dashboards The plugin includes the following pre-built dashboards: - **Query Analysis**: Query performance, time distribution, top users, and memory usage. - **Data Analysis**: Disk usage, table and database summary, parts over time, and dictionaries. - **Cluster Analysis**: Cluster overview, merges, mutations, and replicated table delay. - **OpenTelemetry Logs Explorer**: stacked log volume, services, and per-service samples for OpenTelemetry data exported to `otel_logs`. See the [OpenTelemetry dashboards guide](/docs/plugins/grafana-clickhouse-datasource/latest/dashboards/). - **OpenTelemetry Traces Explorer**: service map, trace search, and per-service performance for OpenTelemetry data exported to `otel_traces`. - **OpenTelemetry Service Dashboard**: single-service deep dive with RED metrics, top errors, slowest operations, related logs, and trace detail. - **ClickHouse System Dashboards**: System metrics (CPU, queries/sec, IO, memory) similar to ClickHouse built-in monitoring. To import a pre-built dashboard: 1. Go to **Connections** > **Data sources**. 2. Select your ClickHouse data source. 3. Click the **Dashboards** tab. 4. 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. > Note > > Plugins are automatically updated in Grafana Cloud. ## Query with the Grafana CLI You can query this data source from the command line and from AI coding agents using the Grafana CLI, `gcx`. `gcx` gives you and your agent structured, terminal-based access to your Grafana data sources, which is useful for automation and agent-driven investigations. `gcx` supports Grafana Cloud and Grafana OSS or Enterprise v12 and later. Before you query, install and authenticate `gcx`. Refer to the [`gcx` CLI documentation](/docs/grafana/latest/as-code/observability-as-code/grafana-cli/gcx/) for installation, configuration, and the full command reference. For example, to query your ClickHouse data source, use `gcx datasources clickhouse`: sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```sh # Run a SQL query gcx datasources clickhouse query -d 'SELECT count() FROM otel_logs' # List tables in a database gcx datasources clickhouse list-tables -d --database otel # Show a table's column schema gcx datasources clickhouse describe-table otel_logs -d --database otel ``` Replace *``* with the UID of your ClickHouse data source. The `query` command accepts SQL with server-side macros such as `$__timeFilter`; `list-tables` and `describe-table` let you explore schema, and `--database` targets a specific database. ## Related resources - [ClickHouse documentation](https://clickhouse.com/docs) - [grafana-clickhouse-datasource on GitHub](https://github.com/grafana/clickhouse-datasource): Source code, issues, and changelog. - [Grafana community forum](https://community.grafana.com/)