Query Builder

This query type will render the data with the table view for Trace Search mode, and the trace panel for Trace ID mode.

## SQL editor[​](#sql-editor "Direct link to SQL editor")

For queries that are too complex for the query builder, you can use the SQL Editor.
This gives you full control over the query by allowing you to write and run plain ClickHouse SQL.

The SQL editor can be opened by selecting "SQL Editor" at the top of the query editor.

[Macro functions](#macros) can still be used in this mode.

You can switch between query types to get a visualization that best fits your query.
This switch also has an effect even in dashboard view, notably with time series data.

## Data links[​](#data-links "Direct link to Data links")

Grafana [data links](https://grafana.com/docs/grafana/latest/panels-visualizations/configure-data-links)
can be used to link to new queries.
This feature has been enabled within the ClickHouse plugin for linking a trace to logs and vice versa. It works best with OpenTelemetry configured for both logs and traces in the [data source's config](/docs/integrations/grafana/config#opentelemetry)

Example of trace links in a table

Example of trace links in logs

### How to make a data link[​](#how-to-make-a-data-link "Direct link to How to make a data link")

You can make a data link by selecting a column named `traceID` in your query. This name is case insensitive, and supports adding an underscore before the "ID". For example: `traceId`, `TraceId`, `TRACE_ID`, and `tracE_iD` would all be valid.

If OpenTelemetry is enabled in a [log](#logs) or [trace](#traces) query, a trace ID column will be included automatically.

By including a trace ID column, the "**View Trace**" and "**View Logs**" links will be attached to the data.

### Linking abilities[​](#linking-abilities "Direct link to Linking abilities")

With the data links present, you can open traces and logs using the provided trace ID.

"**View Trace**" will open a split panel with the trace, and "**View Logs**" will open a logs query filtered by the trace ID.
If the link is clicked from a dashboard instead of the explore view, the link will be opened in a new tab in the explore view.

Having defaults configured for both [logs](/docs/integrations/grafana/config#logs) and [traces](/docs/integrations/grafana/config#traces) is required when crossing query types (logs to traces and traces to logs). Defaults aren't required when opening a link of the same query type since the query can be simply copied.

Example of viewing a trace (right panel) from a logs query (left panel)

## Macros[​](#macros "Direct link to Macros")

Macros are a simple way to add dynamic SQL to your query.
Before a query gets sent to the ClickHouse server, the plugin will expand the macro and replace it will the full expression.

Queries from both the SQL Editor and Query Builder can use macros.

### Using macros[​](#using-macros "Direct link to Using macros")

Macros can be included anywhere in the query, multiple times if needed.

Here is an example of using the `$__timeFilter` macro:

Input:

```
SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)
```

Final query output:

```
SELECT log_time, log_message
FROM logs
WHERE log_time >= toDateTime(1415792726) AND log_time <= toDateTime(1447328726)
```

In this example, the Grafana dashboard's time range is applied to the `log_time` column.

The plugin also supports notation using braces `{}`. Use this notation when queries are needed inside [parameters](/docs/sql-reference/syntax#defining-and-using-query-parameters).

### List of macros[​](#list-of-macros "Direct link to List of macros")

This is a list of all macros available in the plugin:

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Macro Description Output example|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `$__dateFilter(columnName)` Replaced by a time range filter on the provided column using the Grafana panel's time range as a [Date](/docs/sql-reference/data-types/date). `columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23')`| `$__timeFilter(columnName)` Replaced by a time range filter on the provided column using the Grafana panel's time range as a [DateTime](/docs/sql-reference/data-types/datetime). `columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726)`| `$__timeFilter_ms(columnName)` Replaced by a time range filter on the provided column using the Grafana panel's time range as a [DateTime64](/docs/sql-reference/data-types/datetime64). `columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456)`| `$__dateTimeFilter(dateColumn, timeColumn)` Shorthand that combines `$__dateFilter()` and `$__timeFilter()` using separate Date and DateTime columns. Alias `$__dt()` `$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)`| `$__fromTime` Replaced by the starting time of the Grafana panel range cast to a [DateTime](/docs/sql-reference/data-types/datetime). `toDateTime(1415792726)`| `$__fromTime_ms` Replaced by the starting time of the panel range cast to a [DateTime64](/docs/sql-reference/data-types/datetime64). `fromUnixTimestamp64Milli(1415792726123)`| `$__toTime` Replaced by the ending time of the Grafana panel range cast to a [DateTime](/docs/sql-reference/data-types/datetime). `toDateTime(1447328726)`| `$__toTime_ms` Replaced by the ending time of the panel range cast to a [DateTime64](/docs/sql-reference/data-types/datetime64). `fromUnixTimestamp64Milli(1447328726456)`| `$__timeInterval(columnName)` Replaced by a function calculating the interval based on window size in seconds. `toStartOfInterval(toDateTime(columnName), INTERVAL 20 second)`| `$__timeInterval_ms(columnName)` Replaced by a function calculating the interval based on window size in milliseconds. `toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond)`| `$__interval_s` Replaced by the dashboard interval in seconds. `20`| `$__conditionalAll(condition, $templateVar)` Replaced by the first parameter when the template variable in the second parameter doesn't select every value. Replaced by the 1=1 when the template variable selects every value. `condition` or `1=1` | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

- [Query types](#query-types)
  - [Table](#table)- [Logs](#logs)- [Time series](#time-series)- [Traces](#traces)- [SQL editor](#sql-editor)- [Data links](#data-links)
      - [How to make a data link](#how-to-make-a-data-link)- [Linking abilities](#linking-abilities)- [Macros](#macros)
        - [Using macros](#using-macros)- [List of macros](#list-of-macros)

Was this page helpful?