---
source_url: https://www.pubnub.com/docs/illuminate/business-objects/query-builder
title: Query Builder (preview)
updated_at: 2026-06-04T11:10:37.282Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Query Builder (preview)

:::tip Now available for preview
Query Builder is currently in preview. Features and functionality may change.
:::

## About

Query Builder extends metrics by adding flexibility and richer logic. It lets you define conditions and relationships in a more natural, visual way.

For example: *Get the top 10 users who are most engaged by the count of messages. Get users posting duplicate messages to many channels.*

Use the predefined Queries and Decisions in Query Builder to quickly set up ranking and spam detection use cases, view results, and automate the actions you want to trigger. Alternatively, create an [advanced query](#advanced-queries) for full control over how data is transformed and returned.

![Query Builder templates](https://www.pubnub.com/assets/images/predefined-queries-templates-39aa04a13b73cabb7024fae0cfad0bed.png)

## Predefined queries

In this initial preview release, Query Builder includes four predefined queries and Decisions with default configurations:

| Predefined Query | Purpose / Predefined Decision |
| --- | --- |
| **Top N** | Reward the top 10 users who are most engaged: ![Top N predefined query](https://www.pubnub.com/assets/images/top-n-46c014e2bd21c347ffe63857ea1f4461.png) Predefined Decision: ![Predefined decision reward](https://www.pubnub.com/assets/images/predefined-decision-reward-9417090959bd63cbeeaaa31e2f5ebefd.png) |
| **Bottom N** | Incentivize users who are least engaged: ![Bottom N predefined query](https://www.pubnub.com/assets/images/bottom-n-574e330b8295b34f220291abce8ca68d.png) Predefined Decision: ![Predefined decision incentive](https://www.pubnub.com/assets/images/predefined-decision-incentive-8f612e35bc5de6a4d403494273a4b21c.png) |
| **Cross-posting spam** | Detect users sending duplicate messages across multiple channels: ![Cross-posting spam predefined query](https://www.pubnub.com/assets/images/cross-posting-c2dd9a54cc87c2ffff9d44275e629635.png) Predefined Decision: ![Predefined decision flag & optionally restrict](https://www.pubnub.com/assets/images/predefined-decision-flag-and-optionally-restrict-a5db40c06368b84b8f1b7d7f4be2e080.png) |
| **Chat flooding spam** | Detect users posting excessive or repetitive messages in a single channel. ![Chat flooding spam predefined query](https://www.pubnub.com/assets/images/chat-flooding-e24edab378cad90bc105b6e01e12ff05.png) Predefined Decision: ![Predefined decision flag & optionally restrict](https://www.pubnub.com/assets/images/predefined-decision-flag-and-optionally-restrict-flood-5cdc76c54d6540b5bd81e16ccf8f54e6.png) |

## Create a query from a predefined query

1. Click Business Object. Query Builder can be found at the top of the main page of the Business Object when at least one Business Object has been created.
2. Choose one of the available predefined Queries. If you don't see the list, click New query.
3. Provide a name for your query.
4. Add a data source by selecting an active Business Object that is already capturing data. You can also select an inactive Business Object, but note that you won't see any data when you run the query. Once a Business Object is selected, the predefined query automatically preselects the data fields from that object that best match the selected use case. Typically, these fields include User, Channel, and Message Text (or Chat). You can edit the query to meet your use case. The Top N users or Bottom N users can be adjusted to be based on the count of records or rows captured, the count of a specific data field like message chats, the average, sum, max or min of a number data type like purchases or game points.
5. Choose the time period or window you'd like to use for this query (for example, last 1 minute, last 10 minutes, last 1 hour).
6. After selecting the aggregation window, click Save again to store your configuration.
7. Optionally, add filters to refine your results. You can also do this after you run the query. Available filters include: equals, does not equal, greater than, less than,greater than or equal to, less than or equal to, is empty, is not empty, between, not between, contains, does not contain, starts with, ends with, min length, max length
8. Click Run to execute the query and view results. No data appearsIf no data appears, extend the time window (for example, to 1 hour or more) and click Refresh to run the query again. Don't save the extended time window unless that's the aggregation window you actually want to use.
9. Check the query results to verify your setup, add or adjust filters, or refine the query as needed. When used in a Decision, each row displayed in the query results represents a condition that can trigger an action.

## Advanced queries

Advanced queries give you full control over how your data is queried and transformed. Instead of starting from a predefined template, you build the query from scratch by choosing a data source, setting limits, and adding query operations such as aggregations, filters, grouping, sorting, and field selection.

Use an advanced query when the predefined templates don't cover your use case or when you need more granular control over the results.

![Advanced query](https://www.pubnub.com/assets/images/advanced-query-39aa04a13b73cabb7024fae0cfad0bed.png)

### Create an advanced query

1. Click Business Object. Query Builder can be found at the top of the main page of the Business Object when at least one Business Object has been created.
2. Click Create advanced query.
3. Provide a name for your query.
4. Add a data source by selecting a Business Object, if the Business Object isn’t activated, you won’t see any data.
5. Configure the default limits: Period — How far back in time the query looks at data from your data source. The default is 1 hour and the maximum is 1 day., Maximum rows — The maximum number of rows the Query can return. The default and maximum is 500.
6. Optionally, click Run to preview the data.
7. Click Add to query to add one or more query Operations. You can add multiple query operations to shape the results to your needs.
8. Click Save to store your query configuration.

### Query operations

Query operations let you shape and refine the data returned by your query. Click **Add to query** to open the list of available query operations and select one or more to apply.

![Advanced query template](https://www.pubnub.com/assets/images/advanced-query-template-8699818048d4fdabf58d90e81d7d18a7.png)

| Query Operation | Description |
| --- | --- |
| **Aggregation** | Calculates a summary value across data, such as an average, count, count distinct, sum, minimum, or maximum. For example, get the total number of messages sent. |
| **Filter** | Narrows results to only include data that match specific criteria. For example, only show data where the channel name equals "general". |
| **Group By** | Groups data that share the same value in a chosen field, so that aggregations are calculated per group. For example, count messages grouped by user. |
| **Sort By** | Orders the results by a chosen field in ascending or descending order. |
| **Selection** | Chooses which specific fields to include in the Query results, rather than returning all available fields. |

## Create a Decision from a query

Once you've configured and saved a query, you can create a **Decision** that uses the query results to trigger actions. You can create a Decision using a predefined Decision template for predefined queries or start from scratch.

Both options are available directly from the Query Builder.

To create a Decision:

1. Save your query.
2. Click Create Decision. Save the query before creating a DecisionThe Create Decision button is only visible after the query is saved.
3. Choose either Predefined or Create from scratch. Depending on the option you choose, the Decision creation flow is different.

### Use a predefined Decision

Selecting **Predefined** automatically creates a Decision tailored to the selected query template.

What happens automatically:

* A [Decision table](https://www.pubnub.com/docs/illuminate/decisions/basics#rules) is created for the query
* [Conditions](https://www.pubnub.com/docs/illuminate/decisions/basics#conditions) are preconfigured using the query output
* Default [actions](https://www.pubnub.com/docs/illuminate/decisions/basics#actions) are added based on the use case

You can immediately:

* Edit [rules](https://www.pubnub.com/docs/illuminate/decisions/basics#rules), thresholds, and adjust [actions](https://www.pubnub.com/docs/illuminate/decisions/basics#actions)
* Edit the [action configurations](https://www.pubnub.com/docs/illuminate/decisions/basics#actions)
* [Activate the Decision](https://www.pubnub.com/docs/illuminate/decisions/create-decision#activate-decision)

To return to the query at any time, click the **Query name** displayed at the top below the Decision title.

### Create a Decision from scratch

Selecting **Create from scratch** opens a blank Decision configuration.

1. Select Create from scratch.
2. Provide a Decision name (with an optional description).
3. Configure conditions by selecting one of your saved queries. The available data fields correspond to those defined in the query (for example: user, message, channel_count, total_count).
4. Add and configure the desired action. Refer to steps 5-11 of Create Decision to learn more.
5. Create rules that trigger actions when conditions are met. Refer to add conditions and rules.
6. Activate the Decision.

## Terms in this document

* **Business Object** - A container for data fields and metrics that defines aggregations and data sources.