---
source_url: https://www.pubnub.com/docs/analytics/decisions/query-builder
title: Query Builder
updated_at: 2026-09-30T07:20:08.000Z
---

# Query Builder

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

:::tip Preview
Query Builder is in preview. Features and functionality may change.
:::

Query Builder extends [Business Object](https://www.pubnub.com/docs/analytics/decisions/business-objects.md) metrics with a visual query interface and richer filtering logic. Use it to rank users by engagement, detect spam patterns, or build custom aggregations that standard metrics do not support.

Query Builder appears at the top of the **Business Objects** home page in Illuminate when at least one Business Object exists.

## Predefined queries

The initial preview release includes four predefined queries. Each comes with a predefined Decision that includes a default action configuration.

| Predefined query | Use case |
| --- | --- |
| Top N | Find the top 10 users most engaged by message count |
| Bottom N | Find the 10 least engaged users |
| Cross-posting spam | Detect users sending duplicate messages across multiple channels |
| Chat flooding spam | Detect users posting excessive or repetitive messages in a single channel |

When you select a predefined query and assign a Business Object, Illuminate preselects the data fields that best match the use case. The typical fields are User, Channel, and Message Text. You can adjust which field drives the ranking: Top N and Bottom N support count of records, count of a specific field, average, sum, max, or min.

Query results are time-windowed. You set the aggregation window when configuring the query, for example, last 1 minute or last 1 hour.

You can apply filters to refine results. Both predefined and advanced queries support the same set of filter comparators:

`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`

For step-by-step instructions, see [Create a query from a predefined template](https://www.pubnub.com/docs/analytics/decisions/create-predefined-query.md).

## Advanced queries

Advanced queries give you full control over how data is queried and transformed. Instead of starting from a predefined template, you choose a data source, set limits, and chain query operations to shape the results.

Use an advanced query when the predefined templates do not cover your use case or when you need more granular control over the output.

Advanced queries use these default limits:

| Setting | Value |
| --- | --- |
| Period (how far back the query looks) | An advanced Query Builder query looks back 1 hour by default, up to a maximum of 1 day |
| Maximum rows | An advanced Query Builder query returns at most 500 rows |

### Query operations

Click **Add to query** to apply one or more operations that shape the results.

| Operation | What it does |
| --- | --- |
| Aggregation | Calculates a summary value across data: average, count, count distinct, sum, min, or max |
| Filter | Narrows results to rows that match specific criteria |
| Group By | Groups rows that share the same field value so aggregations apply per group |
| Sort By | Orders results by a chosen field in ascending or descending order |
| Selection | Returns only specified fields instead of all available fields |

For step-by-step instructions, see [Create an advanced query](https://www.pubnub.com/docs/analytics/decisions/create-advanced-query.md).

## Connecting queries to Decisions

Each row in the query results represents a condition that can trigger an action when you connect the query to a [Decision](https://www.pubnub.com/docs/analytics/decisions.md). For example, if a Top N query returns 10 users, Illuminate can fire a different action for each user row.

You create a Decision from a saved query in two ways:

* **Predefined Decision** is available for predefined queries. Illuminate auto-creates a Decision table, preconfigures conditions from the query output, and adds default actions for the use case. You can edit rules, thresholds, and actions before activating.
* **Create from scratch** opens a blank Decision. You select conditions from the query's output fields and configure actions manually.

The **Create Decision** button appears in Query Builder after you save the query.

For step-by-step instructions, see [Create a Decision from a query](https://www.pubnub.com/docs/analytics/decisions/create-decision-from-query.md).

Last updated at: 2026-09-30T07:20:08.000Z