# Query builder

Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fcustom-dashboards%2Ftutorials%2Fquery-builder.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fcustom-dashboards%2Ftutorials%2Fquery-builder.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

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

## Overview[​](#overview "Direct link to 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[​](#use-the-query-builder-to-create-a-query "Direct link to 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[​](#metrics-based-query "Direct link to Metrics-based query")

<!--$?-->

<!--/$-->

## Logs-based query[​](#logs-based-query "Direct link to 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.

[![](/assets/images/logs-query-7bf2965a016c810a5dd9b1e3328b1291.webp)](https://docs-docusaurus.kinsta.page/assets/images/logs-query-7bf2965a016c810a5dd9b1e3328b1291.webp)

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

In Builder mode, select logs as your source.

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

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

### Filters[​](#filters "Direct link to 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[​](#functions "Direct link to 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 system automatically divides the selected dashboard time range into **96 equal time buckets**.

The bucket size is calculated dynamically based on the time range picker (for example, **Last 15 Minutes** → \~9-second buckets).

## Spans-based query[​](#spans-based-query "Direct link to 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.

[![](/assets/images/spans-query-a582f9b9e21487b24f8ebab7b9443d53.webp)](https://docs-docusaurus.kinsta.page/assets/images/spans-query-a582f9b9e21487b24f8ebab7b9443d53.webp)

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

In Builder mode, select spans as your source.

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

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

### Filters[​](#filters-1 "Direct link to 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[​](#functions-1 "Direct link to 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 96-bucket time grouping applies here as in log-based queries.

## DataPrime query[​](#dataprime-query "Direct link to DataPrime query")

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

[![](/assets/images/dataprime-query-8f56b1d54be83a35cd002d1d78c95688.webp)](https://docs-docusaurus.kinsta.page/assets/images/dataprime-query-8f56b1d54be83a35cd002d1d78c95688.webp)

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

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

### DataPrime query assistance[​](#dataprime-query-assistance "Direct link to DataPrime query assistance")

Use the [DataPrime Query Assistance](https://docs-docusaurus.kinsta.page/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[​](#convert-to-dataprime "Direct link to 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.

[![](/assets/images/convert-to-dataprime-00093ce8a32ee0dcfee653aef46d585b.webp)](https://docs-docusaurus.kinsta.page/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[​](#widget-time "Direct link to 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[​](#additional-resources "Direct link to Additional resources")

<!-- -->

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

Introduction to PromQL

## Next steps[​](#next-steps "Direct link to Next steps")

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