Custom Dashboards

The built-in monitoring pages answer the questions CHOps decided were worth asking. Custom dashboards answer yours.

You write a SQL query, choose how to draw it, and place the result on a grid with other charts. Nothing is limited to system tables. Any query your connection can run can become a chart, including a query against your own data.

This page covers the three parts, in the order you meet them:

• Chart Builder, where a query becomes a chart.
• My Dashboards, where you arrange charts.
• All Charts, where you find and manage them later.

Who can do what

In the Chart Builder, other roles see the message "Chart building is only available for administrators."

Contents

1. Before you start
2. Chart Builder
3. Chart types
4. Mapping columns
5. Saving a chart
6. My Dashboards
7. Arranging the grid
8. All Charts
9. Making charts interactive
10. When something does not work

1. Before you start

You need a working ClickHouse® connection and a query in mind. If you are not sure what to query, the SQL Editor is a better place to experiment, because you can see the raw results there before you choose a chart type.

A chart is a saved query plus a drawing instruction. It stores your SQL, the chart type, which columns map to which part of the chart, and a name. It does not store data. Every time CHOps shows a chart, it runs the query again against the connection you have selected.

Two things follow from this. A chart is always current, never a stale snapshot. And a chart with a slow query is slow to display, every time.

2. Chart Builder

Find it under Custom Dashboards, then Chart Builder.

The workspace has two panels, stacked vertically. Each one collapses, so you can give room to the panel you work on.

1. SQL & Results, where you write the query, click Run, and see the rows it returned.
2. Config & Preview, where you set the Chart Type, the Subtype, the Chart Name, and the column mapping, and see the chart as it will appear.

The usual rhythm is to write a query, run it, look at the results to see your columns, then configure the chart and watch the preview.

Writing the query

You can run anything your connection allows. Keep the shape in mind, though, because a chart needs columns that map onto its axes. A query that returns one row of forty columns is hard to draw, while forty rows of two columns is easy.

Aggregate in SQL, rather than expecting the chart to do it. GROUP BY and ORDER BY in the query beat any amount of configuration afterward.

If you are not sure how to write it

Qurioz, the built-in AI assistant, turns a plain-English question into ClickHouse® SQL and puts it into the workspace. An administrator enables it by adding a provider key on the AI API Keys page.

It is a starting point, not a final answer. Read what it produces before you save it, the same as you would read a colleague's query.

3. Chart types

There are fifteen types. Several have subtypes that change the arrangement, not the kind of chart.

Choosing between similar ones

Pie against bar. Pie works up to about five categories. Beyond that, the slices are hard to compare, and a horizontal bar chart reads better.

Stacked against grouped bar. Stacked answers "what is the total, and what made it up". Grouped answers "how do these compare". The wrong choice makes the chart correct but hard to read.

KPI against gauge. KPI is a number on its own. Gauge is a number against a range, so it needs a sensible minimum and maximum to mean anything.

Table. A table is not a failure. When someone needs to read exact values, a table is the right answer and a chart is decoration.

Subtypes need different columns

Changing the subtype often changes what the chart needs. A Simple Bar needs a category and a value. A Grouped Bar also needs a series column to group by.

CHOps updates the mapping fields when you change subtype and checks that the columns you chose suit the type. This catches the common mistake of mapping a text column to a numeric axis before you see a broken chart.

4. Mapping columns

Once you choose a type, you tell CHOps which query column plays which role. The fields are named for the chart, not generically. A bar chart asks for a Category and a Value. A scatter chart asks for an X Measure and a Y Measure.

Axis labels and legends

Axis labels fill in from the chart type and your column names. You can override them.

A legend appears on its own when a chart has more than one series, and stays away when it would only take up room.

Gauge minimum and maximum

Gauge charts add fields for the ends of the range. Without them, the gauge has nothing to be a proportion of.

Set them to something meaningful, not to the current value. A disk-usage gauge with a maximum of the current usage always reads full.

The chart toolbar

Every chart has a small toolbar to zoom into a region, reset the view, and save the chart as an image. Any chart expands to full screen, which helps both while you build and while you present.

5. Saving a chart

When the preview shows a chart, the Save to Dashboard panel appears.

1. Select the Dashboard. This field is required.
2. Click Save.

CHOps puts the chart in the next free slot, left to right, then onto the next row, so you do not have to think about position while you build. You can rearrange it later.

If no dashboard exists, the panel shows "Create a dashboard first in the Dashboards section." Create one under My Dashboards first.

A chart belongs to one dashboard. A chart with no dashboard is one whose dashboard someone deleted, and it stays in All Charts.

Editing a chart afterward

Open it from All Charts and choose Edit. The Chart Builder reopens with everything as you left it: the SQL, the type, the subtype, the column mapping, the name, and the dashboard. Click Update to save the changes. To move the chart to another dashboard, select that dashboard before you click Update.

6. My Dashboards

A dashboard is a named grid of charts.

Creating one

Give it a name and choose a Columns count from one to four. That sets how many charts sit side by side. The default is two.

One column suits charts that need width, such as long time series. Two is the usual choice. Three or four suit small charts and KPI tiles, and get cramped on a laptop screen.

The column count is a property of the dashboard and appears beside its name in the list.

What a tile shows

Each chart sits in a tile with its title and a button to view it full screen. Admins also see a delete button (Delete chart (admin only)). This button deletes the chart, not only its place on the dashboard.

Deleting a dashboard

Only admins and super admins can delete a dashboard. CHOps asks "Delete this dashboard? Charts will be unassigned." CHOps does not delete the dashboard's charts. They stay in All Charts with no dashboard.

Which connection charts run against

Charts run against the connection you selected in the navbar. A dashboard is not tied to a cluster, so you can point the same dashboard at production, then at staging, just by changing the connection.

Remember this when a dashboard looks wrong. Check which cluster you are looking at before you investigate the query.

7. Arranging the grid

Drag a chart to swap it with another. The layout updates on screen as you experiment.

CHOps stores nothing until you choose Save Layout. That button appears once you move something, and pressing it keeps the arrangement. If you navigate away without saving, the previous arrangement stays.

This is deliberate. You can try three arrangements and keep the one you like, with no need for an undo.

Ordering that helps

Put the chart that answers "is anything wrong" at the top left, because that is where eyes land first. Detail charts go below. Anything you need only during an investigation goes at the bottom, or on a separate dashboard.

8. All Charts

This is one table of every chart, with the columns Name, Type, Dashboard, and Actions.

Click a row to preview the chart without leaving the list. This is the fastest way to find out what a vaguely named chart shows.

Edit opens it in the Chart Builder with everything filled in.

Delete removes the chart. Only admins and super admins can delete a chart.

The dashboard column is the useful one when you tidy up. Charts with no dashboard come from deleted dashboards.

Naming

The list is only as good as the names. Queries tells you nothing in a list of thirty. Query count by hour, last 7d tells you whether to open it. The name is what you scan later, so spend the extra seconds.

9. Making charts interactive

A chart with fixed values shows one thing. A chart with parameters lets the viewer choose.

Replace a literal with a typed placeholder:

WHERE event_date >= today() - {days:UInt16}

Put that chart on a dashboard, and a control appears above it. Change the value, press Apply, and every chart that uses days runs again. CHOps leaves charts that do not use it alone.

This turns a dashboard from a fixed report into something people use. One dashboard serves the last-day and the last-quarter question, instead of two.

Dashboard Filters covers the syntax, the optional blocks that let a filter disappear when empty, the default values, and how to arrange the controls.

10. When something does not work

The preview is empty but the query returned rows

This is almost always the column mapping. Check that the columns you selected for each role still exist in the results. This is the usual casualty of changing the SQL after you map.

The chart looks wrong after a change of subtype

Subtypes need different columns. Moving from Simple Bar to Grouped Bar adds a series field that starts empty. Re-check the mapping after any subtype change.

A gauge always reads full or empty

Its minimum and maximum are unset or wrong. They define the range the value sits in, so they need to be the bounds you care about, not the value itself.

A dashboard is slow

Each chart runs its own query when it displays, so a dashboard is as slow as the sum of its charts.

Open the slow one in the Chart Builder and run it there to see the time. The usual causes are no date filter, a wide scan, or an aggregation that could happen in ClickHouse® instead of over many returned rows.

The Query Profiler shows where the time went.

My layout changes did not persist

You did not press Save Layout. Dragging alone changes the screen, not the stored arrangement.

A chart shows different numbers than a colleague sees

You have a different connection selected, or different filter values. Check the cluster in the navbar first, then the filter bar.

I deleted a dashboard and its charts are still in All Charts

This is correct. Deleting a dashboard unassigns its charts rather than deleting them. Delete them from All Charts if you want them gone, or edit them and select another dashboard.

Related pages

• Dashboard Filters for interactive dashboards
• SQL Editor to develop a query before it becomes a chart
• Qurioz AI to generate SQL from a question
• Query Profiler when a chart's query is slow
• System Dashboards for the built-in ones