> This page is for Structured Data Models Client.

> 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

PQL describes a predictive task over a relational schema. Every runnable Kumo Relational query identifies a target and the entity or entities to score.

## Target × entity × horizon

* **Target**: The value or event to predict, such as a column or future aggregation.
* **Entity**: The table key for which Kumo Relational returns predictions.
* **Horizon**: The future interval used by a temporal target.

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

## Complete examples

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

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

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

## Current Kumo Relational constraints

These constraints describe the current sdm-pql validator, not every construct in the broader PQL grammar.

| Area             | Current Kumo Relational behavior                                                                                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Entity selection | A query must include `FOR` or `FOR EACH`; applications pass keys through `indices` — up to 100,000 per `materialize()` call, gathered as at most 100 NIM calls, 10,000 entities each (200 for temporal link prediction). |
| 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` requires naming the candidate set with `materialize(..., candidates=...)`; no candidate is assumed. One call is made per candidate.                                                                         |
| Forecasting      | `FORECAST N TIMEFRAMES` is limited to a single entity; one call is made per timeframe.                                                                                                                                   |

See [Write Predictive Queries](/sdgm/kumo-relational/user-guide/make-predictions/writing-predictive-queries) for clause and aggregation details, and [Prediction Types](/sdgm/kumo-relational/user-guide/make-predictions/prediction-types) for ranking and forecasting.

## From query to prediction

```python
from sdm_client import PredictiveQuery, SDMClient, KumoRelational

query = PredictiveQuery(query_text, schema)
request = query.materialize(indices=[42])

with SDMClient(url="http://localhost:8000") as client:
    result = client.predict(request, model=KumoRelational())
```

Continue with the [query-writing tutorial](/sdgm/kumo-relational/user-guide/make-predictions/writing-predictive-queries) or choose a [prediction type](/sdgm/kumo-relational/user-guide/make-predictions/prediction-types).