Plugins 〉ClickHouse

Grafana Labs

Sign up to receive occasional product news and updates:

Data Source


  • Overview
  • Installation
  • Change log
  • Related content

ClickHouse data source for Grafana

Grafana Dashboard Screenshot - Query Analysis Grafana Dashboard Screenshot - Data Analysis

Version compatibility

Users on v8.x of Grafana are encouraged to continue to use v2.2.0 of the plugin. Users on v9.x and higher of Grafana can use v3 however it is beta and may contain bugs.

The ClickHouse data source plugin allows you to query and visualize ClickHouse data from within Grafana.

As of 2.0 this plugin will only support ad hoc filters when using ClickHouse 22.7+


For detailed instructions on how to install the plugin on Grafana Cloud or locally, please checkout the Plugin installation docs.


ClickHouse user for the data source

Set up an ClickHouse user account with readonly permission and access to databases and tables you want to query. Please note that Grafana does not validate that queries are safe. Queries can contain any SQL statement. For example, statements like ALTER TABLE system.users DELETE WHERE name='sadUser' and DROP TABLE sadTable; would be executed.

To configure a readonly user, follow these steps:

  1. Create a readonly user profile following the Creating Users and Roles in ClickHouse guide.
  2. Ensure the readonly user has enough permission to modify the max_execution_time setting required by the underlying clickhouse-go client.
  3. If you're using a public Clickhouse instance, it's not recommended to set readonly=2 in the readonly profile. Instead, leave readonly=1 and set the constraint type of max_execution_time to changeable_in_readonly to allow modification of this setting.

ClickHouse protocol support

The plugin supports both HTTP and Native (default) transport protocols. This can be enabled in the configuration via the protocol configuration parameter. Both protocols exchange data with ClickHouse using optimized native format.

Note that the default ports for HTTP/s and Native differ:

  • HTTP - 8123
  • HTTPS - 8443
  • Native - 9000
  • Native with TLS - 9440

Manual configuration

Once the plugin is installed on your Grafana instance, follow these instructions to add a new ClickHouse data source, and enter configuration options.

With a configuration file

It is possible to configure data sources using configuration files with Grafana’s provisioning system. To read about how it works, including all the settings that you can set for this data source, refer to Provisioning Grafana data sources.

Here are some provisioning examples for this data source using basic authentication:

apiVersion: 1
  - name: ClickHouse
    type: grafana-clickhouse-datasource
      defaultDatabase: database
      port: 9000
      server: localhost
      username: username
      tlsSkipVerify: false
      password: password

Building queries

The query editor allows you to query ClickHouse to return time series or tabular data. Queries can contain macros which simplify syntax and allow for dynamic parts.

Time series

Time series visualization options are selectable after adding a datetime field type to your query. This field will be used as the timestamp. You can select time series visualizations using the visualization options. Grafana interprets timestamp rows without explicit time zone as UTC. Any column except time is treated as a value column.

Multi-line time series

To create multi-line time series, the query must return at least 3 fields in the following order:

  • field 1: datetime field with an alias of time
  • field 2: value to group by
  • field 3+: the metric values

For example:

SELECT log_time AS time, machine_group, avg(disk_free) AS avg_disk_free
FROM mgbench.logs1
GROUP BY machine_group, log_time
ORDER BY log_time


Table visualizations will always be available for any valid ClickHouse query.

Visualizing logs with the Logs Panel

To use the Logs panel your query must return a timestamp and string values. To default to the logs visualization in Explore mode, set the timestamp alias to log_time.

For example:

SELECT log_time AS log_time, machine_group, toString(avg(disk_free)) AS avg_disk_free
FROM logs1
GROUP BY machine_group, log_time
ORDER BY log_time

To force rendering as logs, in absence of a log_time column, set the Format to Logs (available from 2.2.0).

Visualizing traces with the Traces Panel

Ensure your data meets the requirements of the traces panel. This applies if using the visualization or Explore view.

Set the Format to Trace when constructing the query (available from 2.2.0).

If using the Open Telemetry Collector and ClickHouse exporter, the following query produces the required column names (these are case sensitive):

    TraceId AS traceID,
    SpanId AS spanID,
    SpanName AS operationName,
    ParentSpanId AS parentSpanID,
    ServiceName AS serviceName,
    Duration / 1000000 AS duration,
    Timestamp AS startTime,
    arrayMap(key -> map('key', key, 'value', SpanAttributes[key]), mapKeys(SpanAttributes)) AS tags,
    arrayMap(key -> map('key', key, 'value', ResourceAttributes[key]), mapKeys(ResourceAttributes)) AS serviceTags
FROM otel.otel_traces
WHERE TraceId = '61d489320c01243966700e172ab37081'
ORDER BY startTime ASC


To simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros.

Here is an example of a query with a macro that will use Grafana's time filter:

SELECT date_time, data_stuff
FROM test_data
WHERE $__timeFilter(date_time)
MacroDescriptionOutput example
$__timeFilter(columnName)Replaced by a conditional that filters the data (using the provided column) based on the time range of the panel in secondstime >= '1480001790' AND time <= '1482576232' )
$__dateFilter(columnName)Replaced by a conditional that filters the data (using the provided column) based on the date range of the paneldate >= '2022-10-21' AND date <= '2022-10-23' )
$__timeFilter_ms(columnName)Replaced by a conditional that filters the data (using the provided column) based on the time range of the panel in millisecondstime >= '1480001790671' AND time <= '1482576232479' )
$__fromTimeReplaced by the starting time of the range of the panel casted to DateTimetoDateTime(intDiv(1415792726371,1000))
$__toTimeReplaced by the ending time of the range of the panel casted to DateTimetoDateTime(intDiv(1415792726371,1000))
$__interval_sReplaced by the interval in seconds20
$__timeInterval(columnName)Replaced by a function calculating the interval based on window size in seconds, useful when groupingtoStartOfInterval(toDateTime(column), INTERVAL 20 second)
$__timeInterval_ms(columnName)Replaced by a function calculating the interval based on window size in milliseconds, useful when groupingtoStartOfInterval(toDateTime64(column, 3), INTERVAL 20 millisecond)
$__conditionalAll(condition, $templateVar)Replaced by the first parameter when the template variable in the second parameter does not select every value. Replaced by the 1=1 when the template variable selects every value.condition or 1=1

The plugin also supports notation using braces {}. Use this notation when queries are needed inside parameters.

Templates and variables

To add a new ClickHouse query variable, refer to Add a query variable.

After creating a variable, you can use it in your ClickHouse queries by using Variable syntax. For more information about variables, refer to Templates and variables.

Importing dashboards for ClickHouse

Follow these instructions to import a dashboard.

You can also find available, pre-made dashboards by navigating to the data sources configuration page, selecting the ClickHouse data source and clicking on the Dashboards tab.

We distribute the following dashboards with the plugin. These are aimed at assisting with support analysis of a ClickHouse cluster and do not rely on external datasets. The querying user requires access to the system database.

  1. Cluster Analysis - an overview of configured clusters, merges, mutations and data replication.
  2. Data Analysis - an overview of current databases and tables, including their respective sizes, partitions and parts.
  3. Query Analysis - an analysis of queries by type, performance and resource consumption.

Ad Hoc Filters

Ad hoc filters are only supported with version 22.7+ of ClickHouse.

Ad hoc filters allow you to add key/value filters that are automatically added to all metric queries that use the specified data source, without being explicitly used in queries.

By default, Ad Hoc filters will be populated with all Tables and Columns. If you have a default database defined in the Datasource settings, all Tables from that database will be used to populate the filters. As this could be slow/expensive, you can introduce a second variable to allow limiting the Ad Hoc filters. It should be a constant type named clickhouse_adhoc_query and can contain: a comma delimited list of databases, just one database, or a database.table combination to show only columns for a single table.

For more information on Ad Hoc filters, check the Grafana docs

Using a query for Ad Hoc filters

The second clickhouse_adhoc_query also allows any valid Clickhouse query. The query results will be used to populate your ad-hoc filter's selectable filters. You may choose to hide this variable from view as it serves no further purpose.

For example, if clickhouse_adhoc_query is set to SELECT DISTINCT machine_name FROM mgbench.logs1 you would be able to select which machine names are filtered for in the dashboard.

Learn more

Installing ClickHouse on Grafana Cloud:

For more information, visit the docs on plugin installation.




  • Support Point geo data type.


  • Fix timeInterval_ms macro.
  • Fix Table summary and Parts over time panels in Data Analysis dashboard.




  • Add timeInterval_ms macro to allow higher precision queries on DateTime64 columns. #462.


  • Ensure databases, tables, and columns are escaped correctly. #460.
  • Fix conditionAll handling. #459.
  • Fix support for ad-hoc regexp filters: =~, !~ #414.
  • Do not create malformed adhoc filters #451. invalid values will be ignored.
  • Fix auto formatting by reverting to table correctly. #469.
  • Fix parsing of numeric configuration values in yaml file. #456.


  • Stable release of v3.0.4-beta



  • Update ClickHouse driver to v2.9.2


  • Custom ClickHouse settings can be set in data source settings. Allow passing custom ClickHouse settings in datasource
  • Histogram UI fixes Histogram UI fixes
    • Support filter/filter out logs view actions
    • Fix undefined database name by default
    • Reset level and time field properly on table/database change
    • Make it possible to clear the level field (so the histogram will render without grouping by level)
    • Fix filter value that gets stuck in the UI
  • Tracing dashboard added to default dashboards. Tracing dashboard


  • Users on v8.x of Grafana are encouraged to continue to use v2.2.0 of the plugin.
  • Users of Grafana v9.x can use v3 however it is beta and may contain bugs.



  • Chore - Backend binaries compiled with latest go version 1.20.4
  • Custom ClickHouse settings can be set in data source settings. Allow passing custom ClickHouse settings in datasource
  • Standard Golang HTTP proxy environment variables support (HTTP_PROXY/HTTPS_PROXY/NO_PROXY). See FromEnvironment for more information. If the Grafana instance is started with one of these env variables, the driver will automatically load them now.




  • Fix - Quote table names with dots by @slvrtrn in
  • Add a predefined TimeRange filter if there is at least one DateTime* column by @slvrtrn in



  • Chore - Backend binaries compiled with latest go version 1.19.4
  • Chore - Backend grafana dependencies updated to latest version
  • Chore - Clickhouse-go client updated to v2.4.3


  • Chore - Update sqlds to 2.3.17 which fixes complex macro queries
  • Chore - Backend grafana dependency updated
  • Fix - Allow default protocol toggle value when saving in settings


  • Fix - Query builder: allow custom filter values for fields with Map type


  • Chore - Backend binaries compiled with latest go version 1.19.3
  • Chore - Backend grafana dependencies updated


  • Feature - Update sqlds to 2.3.13 which fixes some macro queries


  • Bug - Now works with Safari. Safari does not support regex look aheads


  • Feature - Upgrade driver to support HTTP
  • Feature - Changed how ad hoc filters work with a settings option provided in CH 22.7
  • Feature - Conditional alls are now handled with a conditional all function. The function checks if the second parameter is a template var set to all, if it then replaces the function with 1=1, and if not set the function to the first parameter.
  • Bug - Visual query builder can use any date type for time field
  • Fix - 'any' is now an aggregation type in the visual query builder
  • Fix - Time filter macros can be used in the adhoc query
  • Bug - Time interval macro cannot have an interval of 0
  • Fix - Update drive to v2.1.0
  • Bug - Expand query button works with grafana 8.0+
  • Fix - Added adhoc columns macro


  • Bug - Add timerange to metricFindQuery


  • Bug - Add timeout


  • Feature - Add convention for showing logs panel in Explore


  • Official release


  • Fix - Ignore template vars when validating sql


  • Fix - Time series builder - use time alias when grouping/ordering


  • Chore - Dashboards


  • Fix - timeseries where clause. make default db the default in visual editor


  • Fix - When removing conditional all, check scoped vars (support repeating panels)


  • Fix - When removing conditional all, only remove lines with variables


  • Fix - Handle large decimals properly


  • Feature - Time series builder: use $__timeInterval macro on time field so buckets can be adjusted from query options.


  • Feature - Time series: Hide fields, use group by in select, use time field in group by


  • Feature - Ad-Hoc sourced by database or table


  • Fix - Update sdk to show streaming errors


  • Fix - Format check after ast change


  • Feature - $__timeInterval(column) and $__interval_s macros


  • Fix - Set format when using the new Run Query button.


  • Feature - Query Builder.


  • Fix - Detect Multi-line time series. Handle cases with functions.


  • Feature - Multi-line time series.


  • Bug - Change time template variable names.


  • Bug - Fix global template variables.


  • Bug - Fix query type variables.


  • Bug - Support Array data types.


  • Bug - Fix TLS model.


  • Feature - Add secure toggle to config editor.


  • Initial Beta release.