Connecting Grafana to ClickHouse

The visual query builder suits analysts who want a quick aggregation over a known table without learning the schema in depth. It lets them pick a table, choose columns, apply a count, sum or average, group by a field and set a time column. The raw SQL editor suits engineers who know which ordering key, partition and time column the table uses and who need to control exactly what is read. Most teams give analysts the builder for exploration and keep shared operational dashboards in SQL, so the panels that run every few seconds are written by the people who understand their cost.

• Analyst exploration: the builder is fast for ad hoc counts and breakdowns on small or well-indexed tables.
• Engineering dashboards: SQL is the default for panels that feed incident response or capacity views.
• Review path: agree which dashboards may use the builder before they are shared with the wider organization.
• Schema knowledge: the builder hides the ordering key, so users may not realize a filter is missing.
• Ownership: name an owner for each shared panel who can explain its query.

Confirm with your Grafana and ClickHouse plugin versions which builder options are available in your release, since the plugin documentation is the reference for supported features.

ClickHouse reads data in granules guided by the primary key, which is the table's ordering key in MergeTree tables. When a query filters on the leading columns of that key, the server can skip most of the table. Grafana time range macros turn the dashboard's selected window into a filter on a time column, so the choice of time column and its position in the ordering key determines how much data each refresh touches. A filter on a column outside the key, or a function wrapped around the key column, can force a much wider scan. Partitioning by time can also let the server skip whole partitions when the filter matches the partition expression.

• Ordering key alignment: the time column should lead the ordering key or follow only low-cardinality columns that panels always filter on.
• Function wrapping: avoid expressions such as applying a function to the time column in the WHERE clause when a direct range comparison would do.
• Partition pruning: confirm the partition expression matches the time range the dashboard uses.
• Scan measurement: compare rows read in query logs for the same panel with a narrow and a wide time range.
• Default ranges: set sensible default dashboard ranges so nobody opens a panel over years of data by accident.

Before promoting a panel, check the rows and bytes it reads in the query log for its typical and widest time range, and confirm the table's ordering key with your team.

The builder covers common aggregations, but some panels need constructs it does not express cleanly. These include window functions, multi-step logic with subqueries, conditional aggregation across several metrics, percentiles on large datasets and joins to reference tables. Time-bucketed queries against large tables usually need the bucket expression to match the ordering key so that grouping and filtering stay aligned. Raw SQL also lets engineers pick approximate functions or pre-aggregated tables, which keeps refresh cost stable as data grows. Materialized views and rollup tables often serve these panels better than any query written against raw events.

• Bucketing: use a bucket function that groups by the same time column the filter uses.
• Pre-aggregation: point wide or frequent panels at rollup tables where the schema permits.
• Approximate functions: choose them deliberately and label them on the panel when exact counts are not required.
• Limits: set a row limit or aggregation on every panel that could return unbounded results.
• Macro use: confirm which Grafana macros the plugin expands and check the generated SQL in the query inspector.

Review the generated SQL for each panel and confirm the approach against the plugin's documentation for your versions.

Any user who can edit a panel can change its query, so the editor choice connects to access control. A read-only ClickHouse user limits what a panel can do, but it does not limit how much a query scans. Settings profiles and quotas on that user can cap query duration, memory use and the number of queries over a period, which keeps a careless edit from loading the cluster. Dashboard refresh intervals multiply query load, so a fast refresh on an expensive panel is a common source of cluster pressure. Separating exploration users from dashboard service accounts lets each group have limits that match its work.

• Read-only users: create a dedicated user with select permission only for the databases the dashboards need.
• Profiles and quotas: set query time, memory and rate limits on the Grafana service user and on exploration users.
• Refresh intervals: match refresh rates to how quickly the underlying data changes.
• Editor permissions: restrict who can create or edit shared panels in production folders.
• Auditing: review the query log for panels that consistently read more than their peers.

Confirm the exact access control and quota settings in the ClickHouse access control documentation for your version before you apply them to the Grafana account.

A short written standard keeps panel quality consistent across teams. It should state which editor is allowed for which dashboard type, which time columns and ordering keys each table uses, and what a panel must show before it moves into a shared folder. Reviewers can check the panel against that standard by running it at the widest default range and reading the rows read in the query log. Without a standard, the same question tends to be answered differently by each author, and performance problems appear only after a dashboard is widely used.

• Written standard: document the allowed editor per folder and the required time filter for each large table.
• Range test: run every shared panel at its widest default range before publication.
• Query log check: record rows and bytes read per panel and set a threshold that triggers review.
• Change control: require review when a panel's SQL or refresh interval changes.
• Schema changes: update panels when an ordering key, partition or rollup table changes.

Before rollout, confirm with your team which tables carry the heaviest traffic and agree the review thresholds with the people who own those tables.