---
title: Query builder
description: 'Build Custom Dashboard widget queries without code: filter logs with Lucene and field filters, then count or aggregate them per time interval, such as requests per minute.'
url: https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/query-builder/
product: dashboards
feature: Dashboards
feature_id: dashboards
feature_identifier: dashboards/dashboards
last_updated: '2026-11-09'
---

# 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 DataPrime, 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

<!--$?-->

<!--/$-->

## 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.

[![](/docs/assets/images/logs-query-7bf2965a016c810a5dd9b1e3328b1291.webp)](https://coralogix.com/docs/assets/images/logs-query-7bf2965a016c810a5dd9b1e3328b1291.webp)

Note

Dashboard widgets support the `$l.` (label) and `$m.` (metadata) Lucene field prefixes, matching Explore, e.g. `$l.applicationname: "checkout"`. Both Lucene and DataPrime query modes resolve these fields consistently.

### Data source

In Builder mode, select logs as your source.

### Data pipeline

Choose to query [Frequent Search](https://coralogix.com/docs/user-guides/account-management/tco-optimizer.md#tco-priority-levels-explained) or [Monitoring](https://coralogix.com/docs/user-guides/account-management/tco-optimizer.md#features-by-priority-level) logs.

### Dataset (logs)

Early access

The dataset selector is available to accounts with early access. Contact your Coralogix account representative to request it. Without it, the query builder works as described in [Data pipeline](#data-pipeline).

With the dataset selector, you choose which [dataset](https://coralogix.com/docs/user-guides/data-layer/dataset-management.md) a logs query reads from. The selector replaces the data pipeline choice, because the dataset determines the pipeline:

* The built-in `default/logs` dataset queries Monitoring logs.
* Datasets in the `frequentsearch` dataspace query Frequent Search logs.

New widgets, filters, variables, and annotations start on `default/logs` or `default/spans` when your account has an archive configured and you can read Monitoring data. Otherwise, they start on `frequentsearch/logs` or `frequentsearch/spans`.

You can select one dataset per query. The selector lists only the datasets your team can query. If a saved widget refers to a dataset that your team can no longer query, the widget editor shows an error that names it.

The dataset selector is also available for logs and spans in dashboard filters, variables, and annotations. It is not available for metrics or PromQL queries.

### 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.

| Function           | Description                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Count**          | The total number of data points within the selected time range.                                                                            |
| **Count Distinct** | The number of unique data points within the selected time range.                                                                           |
| **Sum**            | The sum of all data points within the selected time range.                                                                                 |
| **Min**            | The smallest value among the data points within the selected time range.                                                                   |
| **Max**            | The largest value among the data points within the selected time range.                                                                    |
| **Average**        | The average value of all data points within the selected time range.                                                                       |
| **Percentile XX**  | Represents 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.

Note

In time-based visualizations, when you use **Group By** with a **timestamp** field in logs or spans queries, the widget divides the selected dashboard time range into equal time buckets.

The number of buckets is not fixed. On **Auto**, the widget derives it from how wide the widget is drawn, at roughly one data point per two pixels, then applies a cap for the data mode and widget type. A wider widget therefore resolves more finely than a narrow one over the same time range.

The cap is 200 data points on Frequent Search, 500 on bar charts, and 1,000 otherwise. Set the interval yourself with **Manual**, or change the cap under **Limits (advanced)**. See [Configure time interval](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/configure-time-interval.md).

## 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.

[![](/docs/assets/images/spans-query-a582f9b9e21487b24f8ebab7b9443d53.webp)](https://coralogix.com/docs/assets/images/spans-query-a582f9b9e21487b24f8ebab7b9443d53.webp)

### 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](https://coralogix.com/docs/user-guides/account-management/tco-optimizer.md).

### Dataset (spans)

For accounts with the early access [dataset selector](#dataset-logs), spans queries can also select a dataset. The selector appears for [dynamic widgets](https://coralogix.com/docs/user-guides/custom-dashboards/widgets/dynamic-widget.md). It doesn't appear for other spans widgets or on [relational queries](https://coralogix.com/docs/user-guides/data-query/relational-queries.md), which always read from the Monitoring spans pipeline.

### 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.

| Function           | Description                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Count**          | The total number of data points within the selected time range.                                                                            |
| **Count Distinct** | The number of unique data points within the selected time range.                                                                           |
| **Sum**            | The sum of all data points within the selected time range.                                                                                 |
| **Min**            | The smallest value among the data points within the selected time range.                                                                   |
| **Max**            | The largest value among the data points within the selected time range.                                                                    |
| **Average**        | The average value of all data points within the selected time range.                                                                       |
| **Percentile XX**  | Represents 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 1 or more fields. The same time bucketing applies here as in log-based queries.

## DataPrime query

You may create a [DataPrime](https://coralogix.com/docs/dataprime/introduction/welcome-to-the-dataprime-reference.md) query as the basis for your widget.

[![](/docs/assets/images/dataprime-query-8f56b1d54be83a35cd002d1d78c95688.webp)](https://coralogix.com/docs/assets/images/dataprime-query-8f56b1d54be83a35cd002d1d78c95688.webp)

### Data pipeline

Choose to query Frequent Search or Monitoring data. Find out more about TCO pipelines for logs [here](https://coralogix.com/docs/user-guides/account-management/tco-optimizer.md) and for spans [here](https://coralogix.com/docs/user-guides/account-management/tco-optimizer.md).

### DataPrime query assistance

Use the [DataPrime Query Assistance](https://coralogix.com/docs/user-guides/olly/dataprime-query-assistance.md) to describe your query in natural language and the system will transform your input into a structured query.

## Convert to DataPrime

When you create a logs-based or spans-based query, you have the option of converting it to DataPrime syntax language by clicking **Convert to DataPrime** in the upper right corner of the Builder.

[![](/docs/assets/images/convert-to-dataprime-00093ce8a32ee0dcfee653aef46d585b.webp)](https://coralogix.com/docs/assets/images/convert-to-dataprime-00093ce8a32ee0dcfee653aef46d585b.webp)

When you do, the transformed query will appear under the DataPrime tab in the Builder.

Note

Once you change data sources or convert your query to DataPrime, your original query parameters in the Builder will be lost. Saving your widget will preserve the most recent state of the widget.

## 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.

## Additional resources

<!-- -->

![Introduction to PromQL](https://img.youtube.com/vi/j78ll9mqDNg/mqdefault.jpg)

Introduction to PromQL

## Next steps

Learn how to [create and manage variables](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/create-and-manage-variables.md) for your dashboards.