Skip to content

Query Builder

Create complex queries easily using the Query Builder in Custom Dashboards.

Overview

Using the Custom Dashboards Query Builder, you can now build queries for your widgets without the burden of knowing the exact Lucene or PromQL syntax.

Use the Query Builder to create a query

During your widget setup, a query panel will appear in the lower part of the dashboard panel. Toggle between Builder and Query modes.

Metrics-based query

Data source

In Builder mode, select metrics as your source.

Metric name

Choose your preferred metric from a dropdown menu that is dynamically filled with available metrics. Use the autocomplete capability to explore the metric name, labels, and values.

Filters

To add a filter, click +. Choose a metric label and an associated value to filter your metric.

Select the = or != operator from the drop-down menu to include or exclude one or more values, respectively. Selecting the =~ or !~ operators will allow you to input a regex expression.

To add additional label-value pairs, click the + button.

Functions

Selecting metrics and labels already builds a valid Prometheus query, but you can create more complex queries using functions.

To add a function, click +. Select between aggregation, count and rollup functions.

Aggregation

Aggregation functions calculate a set of values and return a single value. These functions include SUM(), AVG(), MIN(), MAX(), COUNT(), and others. Once you choose the function, select the label to aggregate in the dropdown menu or type it.

AggregationDescription
averageThe average value of all data points within the selected time range.
countThe total number of data points within the selected time range.
minThe smallest value among the data points within the selected time range.
maxThe largest value among the data points within the selected time range.
sumThe sum of all data points within the selected time range.
quantileThe quantile(phi, q) by (group_labels) function is an aggregate that computes the phi-quantile for each group of labels within the time series returned by q. The value of phi must fall within the range [0...1]. The quantile is calculated separately for each set of points that share the same timestamp. This function is supported by PromQL.
histogram_quantileThe histogram_quantile function is a transformation function that computes the phi-percentile based on the provided histogram buckets. The value of phi must be between [0...1]. For example, histogram_quantile(0.5, sum(rate(http_request_duration_seconds_bucket[5m])) by (le)) returns the median request duration for all requests in the last 5 minutes.

Count

Count functions perform calculations on a set of values and return a single value. These functions include Count(), Absent(), Absent over time(), Present over time(), Changes(), Resets()and others.

CountDescription
countThe total number of data points within the selected time range.
absentReturns 1 if time series have no points. Otherwise, it returns an empty result.
absent over timeReturns 1 if the provided time range does not contain raw samples.
present over timeReturns 1 if there is at least a single raw sample in the provided time range.
changesThe number of times that the time series value has changed within the provided time range.
resetsThe number of counter resets within the provided time range.

Rollup

A rollup function refers to functions that aggregate time series data over a specified time range. These functions compute metrics like average (avg_over_time), sum (sum_over_time), minimum (min_over_time), maximum (max_over_time), count (count_over_time), and quantiles (quantile_over_time) over a window of time. They are used to summarize and analyze metric data.

RollupDescription
average over timeComputes the average of time series values over a time range.
max over timeFinds the maximum value of time series data over a time range.
min over timeDetermines the minimum value of time series data over a time range.
sum over timeCalculates the sum of time series values over a time range.
count over timeCounts the number of non-NaN elements in the time series over a time range.
quantile over timeComputes the specified quantile of time series data over a time range.

Once you choose the function, select the range to be queried as a hard number or ${__range}. This variable represents the duration of the dashboard time range. It is rendered as an interval string supported by PromQL. For example, if one selects a time range from 13.00 to 14.30, the ${__range} variable will be rendered as 90m. For detailed information about pre-defined variables, see this tutorial.

Rank

Rank functions allow you to sort, rank, and filter data within your queries. You can use them to refine your results based on specific metrics and values.

To add a rank function, click + and choose from TOPK, SORT, or SORT Descending. Once you select a rank function, configure it by specifying the metric and parameters (e.g., populate the number of K results you would like the query to retrieve for TOPK).

Rank FunctionDescription
TOPKRetrieves the top K results from a dataset based on a specified metric. Use this to show the highest-ranking data points.
SORTOrders data in ascending order based on the selected metric. Use this to organize data from the smallest to the largest value.
SORT DescendingOrders data in descending order based on the selected metric. Use this to prioritize the largest values at the top of the result set.

Logs-based query

The logs-based Query Builder allows you to create complex queries by crafting Lucene-based queries and then adding filters and functions.

Data source

In Builder mode, select logs as your source.

Data pipeline

Choose to query Frequent Search or Monitoring logs.

Filters

To add a filter, click +. Choose a label and an associated value.

Select the = or != operator from the drop-down menu to include or exclude one or more values, respectively. Selecting the =~ or !~ operators will allow you to input a regex expression.

To add additional label-value pairs, click the + button.

Functions

To add a function, click +. Show an aggregated value using one of the following functions.

FunctionDescription
CountThe total number of data points within the selected time range.
Count DistinctThe number of unique data points within the selected time range.
SumThe sum of all data points within the selected time range.
MinThe smallest value among the data points within the selected time range.
MaxThe largest value among the data points within the selected time range.
AverageThe average value of all data points within the selected time range.
Percentile XXRepresents the value below which XX% of the data points fall. For example, Percentile 95 is the value below which 95% of data points fall.

With Group by, you may group query results by one or more fields.

Spans-based query

The spans-based Query Builder allows you to create complex queries by crafting Lucene-based queries and then adding filters and functions.

Data source

In Builder mode, select spans as your source.

Data pipeline

Choose to query Frequent Search or Monitoring spans. Find out more about TCO pipelines for spans here.

Filters

To add a filter, click +. Choose a label and an associated value.

Select the = or != operator from the drop-down menu to include or exclude one or more values, respectively. Selecting the =~ or !~ operators will allow you to input a regex expression.

To add additional label-value pairs, click the + button.

Functions

To add a function, click +. Show an aggregated value using one of the following functions.

FunctionDescription
CountThe total number of data points within the selected time range.
Count DistinctThe number of unique data points within the selected time range.
SumThe sum of all data points within the selected time range.
MinThe smallest value among the data points within the selected time range.
MaxThe largest value among the data points within the selected time range.
AverageThe average value of all data points within the selected time range.
Percentile XXRepresents the value below which XX% of the data points fall. For example, Percentile 95 is the value below which 95% of data points fall.

With Group by, you may group query results by one or more fields.

DataPrime query

You may create a DataPrime query as the basis for your widget.

Data pipeline

Choose to query Frequent Search or Monitoring data. Find out more about TCO pipelines for logs here and for spans here.

DataPrime Query Assistant

Use the DataPrime Query Assistant to describe your query in natural language and the system will transform your input into a structured query.

Widget time

The dashboard's overall time picker sets the default timeframe for your query. To customize the timeframe for this widget alone, click Widget time and switch off the toggle to unlink it from the dashboard’s timeframe. You can then choose a standard or custom timeframe for this widget specifically.

Support

Need help?

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to contact us via our in-app chat or by emailing [email protected].