Introducing the official ClickHouse plugin for Grafana

This blog post was co-authored by ClickHouse Senior Director of Developer Advocacy Tyler Hannan and Grafana Labs Software Engineer Andrew Hackmann.

We are delighted to introduce the new first-party ClickHouse plugin for Grafana, developed by Grafana in collaboration with ClickHouse. Grafana is committed to continuing our partnership and maintaining this plugin, and we’re excited to add more features and to grow with ClickHouse.

But why Grafana + ClickHouse?

ClickHouse is known for its extremely high query processing speed and excellent data storage efficiency. Grafana is known for its “big tent” approach to observability, enabling users to access data wherever it lives in order to build beautiful and compelling dashboards quickly. The combination of the two means you can ingest, interact with, and understand your data both programmatically and visually.

On the technical side, the official ClickHouse plugin is an open source project hosted on GitHub and implemented in TypeScript and Go. The ClickHouse plugin follows all Grafana standards for plugins, with the backend using sqlds library, and the frontend using React and core Grafana React components. This allows the plugin to be lightweight and easy to maintain.

How does the ClickHouse plugin for Grafana work? 

The plugin adds the ClickHouse data source type to Grafana. If you have used Grafana to query another DBMS (via SQL), you might have an idea of how such plugins work; if not, read along.

The data source creation is simple: You provide an endpoint with credentials, optionally tune some settings, test that it works, and that’s it. Keep in mind that, unlike the community plugin, this one works over the Native TCP protocol.

Then comes the most exciting part: creating visualizations using the ClickHouse data source. In the simplest scenario, you’ll need a ClickHouse SQL query that returns tabular data. Pass this to any Grafana visualization and configure its representation (keep in mind that most visualizations have requirements to the source data, most notably for data types). If you want to spice it up further, the plugin supports Grafana macros for extra flexibility and to support dynamic behavior such as drill downs.

If your SQL skills are rusty, or if you just want to save some time on typing a simple query, the plugin also provides a visual Query Builder mode:

Created panels can be arranged into a variety of dashboards that can be customized by each user. The plugin also comes with pre-built dashboards; currently, they include Data Analysis, Cluster Analysis, and Query Analysis. These should work with any ClickHouse instance or cluster based on the modern official open source builds. Each pre-built dashboard has template variables that you can set to drill down into specific databases, tables, queries, and more.

Pre-built dashboards in the ClickHouse plugin

A number of technical considerations went into this first-party ClickHouse plugin. This includes building a plugin that is more in line with some of the advancements in core Grafana: moving to a TCP connection, SQL editor suggestions, moving the backend to Grafana’s core sqlds library, and moving the frontend from Angular.js to React to align with core Grafana React components. As a first-party plugin, it is fully up-to-date with our current design patterns, and we value your feedback on the future and our roadmap.

Learn more about the ClickHouse plugin

If you want to try this plugin, feel free to go through the Grafana+ClickHouse tutorial based on the COVID dataset. Or you can read our ClickHouse plugin documentation and install the plugin on your (pre-)production Grafana instance to play around. 

You can also watch the on-demand webinar “Real-time SQL analytics at scale: A story of open source GitHub activity using ClickHouse and Grafana” to learn more about successful open source projects that use the ClickHouse plugin for Grafana.

If you’re an existing Grafana user but new to ClickHouse, you can use the public ClickHouse Playground to skip initial installation and get started faster. 

If you’re new to Grafana, Grafana Cloud is the easiest way to get started with metrics, logs, traces, and dashboards. You can sign up for our generous free forever tier and learn more about our plans for every use case.

Of course, our thanks go out to the ClickHouse team for partnering with us on this new plugin! As for future development, the ClickHouse plugin follows the typical open source workflow, with all upcoming features and issues published and discussed on GitHub and often shared in the ClickHouse newslettter. We welcome contributions both to the discussion and to the code itself!