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

# Query Kumo Relational

> Understand the target, entity, horizon, and current Kumo Relational PQL constraints

Predictive Query Language (PQL) tells Kumo Relational what to predict from tables connected in a relational graph and which records should receive predictions.
Use a PQL query to turn a business question into a request that identifies a target and one or more entities.
For predictions about future activity, the query also specifies a time horizon.

## Target × entity × horizon

Read a predictive query by answering three questions: What should Kumo Relational predict, which records need predictions, and how far into the future should it predict?

![Target, entity, and horizon in a predictive query](/sdgm/_fern-img/e5977548eab06d423abec74d9a7541ccb070290fbc8e81c66c4a2267df64d067.webp)

* **Target**: The value or event to predict, such as an existing column value or an aggregation of future activity.
* **Entity**: The table key that identifies each record for which Kumo Relational returns a prediction.
* **Horizon**: The future interval for a temporal target, measured from the time at which the prediction is made.

In the following pattern, angle brackets mark required values and square brackets mark optional clauses:

```text
PREDICT <target_expression>
FOR <entity_table>.<primary_key> <entity_selection>
[WHERE <context_filter>]
[ASSUMING <condition>]
```

`WHERE` filters the historical context used for a prediction.
`ASSUMING` conditions the prediction on a hypothetical attribute value.

## Complete examples

The target expression determines the type of prediction and whether the query needs a future horizon.

```sql
-- Regression: spend during the next 30 days
PREDICT SUM(orders.amount, 0, 30, days)
FOR customers.customer_id=42
```

This query returns the predicted total order amount for customer `42` during the next 30 days.

```sql
-- Classification: any order during the next 30 days
PREDICT COUNT(orders.*, 0, 30, days) > 0
FOR customers.customer_id IN (42, 57, 81)
```

This query returns a prediction of whether each listed customer will place at least one order during the next 30 days.

```sql
-- Static target on the entity table
PREDICT customers.segment
FOR customers.customer_id=42
```

This query predicts the `segment` value for customer `42`.
It does not need a horizon because the target is a column on the entity table rather than an aggregation of future activity.

## Current Kumo Relational constraints

These limits apply when Kumo Relational validates a query.
The broader PQL grammar can describe constructs that Kumo Relational does not currently accept.

| Area             | Current Kumo Relational behavior                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Entity selection | A query must include `FOR` or `FOR EACH`; applications can also provide up to 1,000 entity IDs through the `indices` argument. |
| Static filters   | Column-value filters are limited to the same table; joined static filters are not supported.                                   |
| Static targets   | A non-aggregated target must be on the entity table.                                                                           |
| Ranking          | `RANK TOP K` supports at most 20 results.                                                                                      |
| Forecasting      | Forecasting is limited to a single entity and supports at most 10,000 timeframes.                                              |

See [Write Predictive Queries](/kumo-relational/user-guide/make-predictions/writing-predictive-queries) for clause and aggregation details.

## Submit Your Query

Follow [Make Predictions](/kumo-relational/user-guide/make-predictions/make-predictions)
to bind a graph to the client, submit the query, and select entities.
For a worked query-authoring exercise, see
[Write Predictive Queries](/kumo-relational/user-guide/make-predictions/writing-predictive-queries).