> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Predictive Query Structure

> **Prerelease documentation**
>
> This Kumo Studio information is prerelease and is not yet supported. Stay tuned for the Docker and Kubernetes releases.

A **Predictive Query** defines a predictive modeling task in Kumo using **PQL (Predictive Query Language)**, a SQL-like syntax that specifies:

* **Target** – What you want to predict.
* **Entity** – Who you are making predictions for.
* **Filters (optional)** – Constraints on which entities or data to include.

![Predictive Query structure diagram showing Target, Entity, and Filters](/sdgm/_fern-img/85b0188892f8bea0ccf452a15cf2bf695bfdaabd4d29302e63054525614330dd.webp)

## Target

The **target** is the outcome you want to predict, defined after the `PREDICT` command.

For example, to predict **total purchases per user over the next 30 days**, the target is **"sum of purchases over the next 30 days."**

## Entity

The **entity** is the subject of your prediction: **who** the prediction is being made for.

For example, if predicting **total purchases per user**, then the **user** is the entity.

## Aggregation Operators

When predicting an **aggregation over time** (for example, total sales over 30 days), use an **aggregation function** with a column reference.

**Example: Predicting Total Purchase Value per Customer**

**`PQL`**

```Text PQL
PREDICT SUM(TRANSACTIONS.PRICE, 0, 30)
FOR EACH CUSTOMERS.CUSTOMER_ID
```

* `SUM(TRANSACTIONS.PRICE, 0, 30)` → Sums purchase values over the next **30 days**.
* `FOR EACH CUSTOMERS.CUSTOMER_ID` → Predicts **for each customer**.

![Aggregation operator example showing SUM function in a Predictive Query](/sdgm/_fern-img/b54b9e608f84df6350c309ac90f6049117c1d001cd8eaa12fed7a2971a684a7a.webp)

The *start* boundary is exclusive and the *end* boundary is inclusive.
For example, start=10 and end=30 aggregates from 10 days later (excluding day 10) to 30 days later (including day 30).

If you're making the prediction on `2020-01-01 00:00:00`, Kumo aggregates all rows with timestamps *t* where `2020-01-11 00:00:00 < t <= 2020-01-31 00:00:00`.

Both *start* and *end* must be non-negative integers, and *end* must be greater than *start*.

### Common Aggregation Functions

* `SUM()` – Total value over time.
* `COUNT()` – Number of occurrences over time.

### Aggregation Window (Start & End)

* The **start** and **end** parameters define the **prediction window** in days.
* If the prediction date is `2020-01-01`:
  * `10, 30` predicts transaction values from **`2020-01-11 to 2020-01-31`**.

**`PQL`**

```Text PQL
PREDICT SUM(TRANSACTIONS.PRICE, 10, 30)
FOR EACH CUSTOMERS.CUSTOMER_ID
```

### Aggregation Units

The time unit defaults to **days**, but can also be:

* `days` (default)
* `months`
* `hours`

**`PQL`**

```Text PQL
PREDICT SUM(TRANSACTIONS.PRICE, 0, 30, months)
FOR EACH CUSTOMERS.CUSTOMER_ID
```

## Filters (`WHERE`)

Filters refine a Predictive Query by **removing irrelevant entities or restricting aggregation conditions**.

For example, to **predict purchases for active customers only** (that is, those who made at least one transaction in the past 30 days):

**`PQL`**

```Text PQL
PREDICT SUM(TRANSACTIONS.PRICE, 0, 30)
FOR EACH CUSTOMERS.CUSTOMER_ID 
WHERE COUNT(TRANSACTIONS.*, -30, 0) > 0
```

Kumo supports **advanced filtering**, including:

* Inline filters inside aggregations
* Nested temporal filters
* Static date/time filters
* Multiple target conditions (`AND`/`OR`)