Analytics Query Language
This page documents the SQL meta-comment language used by the Analytics / Query Explorer. The feature and its syntax are under active development and may change.
The Query Explorer uses a lightweight meta-comment language embedded in SQL comments to drive chart rendering, drill-down navigation, and time-range filtering. Any ClickHouse SQL query can become a fully interactive preset by adding a few -- @directive lines at the top.
These directives are also used by Grafana panel export. When TraceHouse runs inside Grafana, Query Explorer can turn the current query and visualization into Grafana panel JSON.
Directives
@meta - Query metadata
Defines the query's identity and display properties.
-- @meta: title='Memory Usage Trend' group='Resources' description='Memory usage over the last 24 hours' interval='1 DAY'
| Parameter | Required | Description |
|---|---|---|
title | Yes | Display name shown in the sidebar and query header |
group | Yes | Category tab (Overview, Inserts, Selects, Parts, Merges, Resources, Advanced Dashboard, Self-Monitoring, or any custom name) |
description | No | Short description shown as a tooltip / subtitle |
interval | No | Default time range, e.g. 1 DAY, 2 HOUR, 7 DAY. Used with {{time_range}} placeholders |
@chart - Chart configuration
Tells the explorer how to visualise the result set.
-- @chart: type=bar group_by=table value=bytes_size style=3d
| Parameter | Required | Description |
|---|---|---|
type | Yes | Chart type: bar, line, pie, area, grouped_bar, stacked_bar, grouped_line |
group_by | Yes | Column name to use for the X-axis / category grouping |
value | Yes | Column name(s) for the Y-axis. Can be a single column or comma-separated list (e.g. value=p50,p95,p99) |
series | No | Column name used for series splitting (for grouped_bar, stacked_bar, grouped_line) |
style | No | 2d (default SVG/recharts) or 3d (Three.js) |
unit | No | Unit suffix for value axis ticks, e.g. ms, s, MB, %. Time units (ms, s) auto-scale (e.g. 1400 ms → 1.4 s) |
orientation | No | horizontal (default for grouped/stacked bars) or vertical (shorthand v). Controls bar direction — horizontal puts labels on the left for readability |
color | No | Override the default chart color with a hex value (e.g. #f59e0b) |
@drill - Drill-down navigation
Enables click-to-drill: clicking a chart segment navigates to another query, passing the clicked value as a filter.
-- @drill: on=database into='Table Sizes'
| Parameter | Required | Description |
|---|---|---|
on | Yes | Column whose clicked value is passed to the target query |
into | Yes | Title of the target query to navigate to |
@link - Popup link to another query
Makes a table column clickable. Clicking a cell value opens a modal popup that runs a target query with the clicked value passed as a drill parameter. Unlike @drill which navigates away, @link keeps your current view and overlays the results.
-- @link: on=query_hash into='App Query Executions'
| Parameter | Required | Description |
|---|---|---|
on | Yes | Column whose clicked value is passed to the target query |
into | Yes | Title of the target query to open in the popup |
The target query receives the clicked value via the standard {{drill:column | fallback}} or {{drill_value:column | fallback}} placeholders.
@cell - Table cell decoration
Decorates table columns with visual styles. Each @cell: line targets one column with one decoration type. Multiple @cell: lines can target the same column (e.g. gauge + rag).
| Parameter | Required | Description |
|---|---|---|
column | Yes | Column name to decorate |
type | Yes | Decoration type: rag, gauge, or sparkline |
type=rag — Red / Amber / Green coloring
Applies conditional coloring to table cells. Only affects table view.
Numeric (ascending — lower is better):
-- @cell: column=avg_bytes_read type=rag green<2000 amber<40000
Numeric (descending — higher is better):
-- @cell: column=uptime_days type=rag green>30 amber>7
Text mode — match exact string values:
-- @cell: column=status type=rag green=ok,healthy amber=degraded red=error,down
type=gauge — Inline horizontal bar
Renders a column as a horizontal gauge bar in the table. Combine with type=rag on the same column for colored bars.
-- @cell: column=used_pct type=gauge max=100 unit=%
-- @cell: column=used_pct type=rag green<70 amber<85
-- @cell: column=disk_used type=gauge max=disk_total unit=TiB
| Parameter | Required | Description |
|---|---|---|
max | Yes | Bar's 100% value — a fixed number (e.g. 100) or another column name (e.g. disk_total) |
unit | No | Unit suffix displayed beside the value |
type=sparkline — Inline trend line
Renders a column as a tiny SVG trend in the table. The column should contain an array of numeric values (e.g. from groupArray()).
-- @cell: column=disk_delta type=sparkline ref=0
-- @cell: column=query_rate type=sparkline color=#f59e0b fill=true
| Parameter | Required | Description |
|---|---|---|
ref | No | Horizontal reference line value (e.g. 0 for delta charts) |
color | No | Hex color for the sparkline stroke |
fill | No | true to fill the area under the line |
Multiple decorations on different columns:
-- @cell: column=memory_pct type=gauge max=100 unit=%
-- @cell: column=memory_pct type=rag green<60 amber<85
-- @cell: column=cpu_pct type=gauge max=100 unit=%
-- @cell: column=disk_delta type=sparkline ref=0
Template placeholders
{{time_range}}
Replaced at execution time with a ClickHouse time expression based on the user-selected time range or the @meta interval default.
WHERE event_time > {{time_range}}
When using the time picker's custom range, {{time_range}} resolves to a toDateTime('...') expression with both start and end bounds injected automatically.
{{drill:column | fallback}}
Replaced with a filter condition when the query is reached via drill-down, or with the fallback expression otherwise.
WHERE {{drill:database | 1=1}}
- When drilled into with
database = 'nyc_taxi'→WHERE database = 'nyc_taxi' - When opened directly →
WHERE 1=1
{{drill_value:column | fallback}}
Like {{drill:column | fallback}} but resolves to just the quoted value instead of a full equality condition. Useful when the drill parameter needs a custom expression (e.g. computed column matching):
WHERE lower(hex(normalized_query_hash)) = {{drill_value:query_hash | ''}}
- When linked/drilled with
query_hash = '52794d32e666dd45'→WHERE lower(hex(normalized_query_hash)) = '52794d32e666dd45' - When opened directly →
WHERE lower(hex(normalized_query_hash)) = ''
{{cluster_aware:db.table}}
On a single-node setup, resolves to the bare table reference db.table. On a cluster, wraps it with clusterAllReplicas('cluster_name', db.table) so that per-node tables like system.query_log are fanned out to all replicas. Queries using this should deduplicate with GROUP BY since replicas may return overlapping rows.
SELECT query, count()
FROM {{cluster_aware:system.query_log}}
WHERE event_time > {{time_range}}
GROUP BY query
{{cluster_name}}
Resolves to the quoted cluster name on a cluster, or an empty string on single-node. Useful for conditional logic or display.
Source attribution
A -- Source: comment (not a directive) adds an attribution link to the query card, typically pointing to ClickHouse docs or knowledge base articles.
-- Source: https://clickhouse.com/docs/operations/system-tables/parts
Full example
-- @meta: title='Database Sizes' group='Overview' description='Total disk usage per database'
-- @chart: type=pie group_by=database value=total_bytes style=3d
-- @drill: on=database into='Table Sizes'
-- @cell: column=total_bytes type=rag green<1000000000 amber<10000000000
SELECT
database,
sum(bytes_on_disk) AS total_bytes
FROM system.parts
WHERE active
GROUP BY database
ORDER BY total_bytes DESC
This query appears in the Overview group, renders as a 3D pie chart, clicking a slice drills into the "Table Sizes" query filtered to that database, and in table view the total_bytes column is color-coded green/amber/red based on size.