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

# Prediction Types

> Task taxonomy: regression, classification, forecasting, ranking, and static tasks

Kumo Relational uses connected tables to predict numeric values, classes, ranked items, and time series.
Use this reference to choose between **temporal tasks**, which predict outcomes over a future time horizon, and **static tasks**, which infer current or unknown attributes without a time component.

Each example shows a query in Predictive Query Language (PQL), Kumo Relational's SQL-like language for describing what to predict and which entity to predict it for.
The Python snippets run those queries with the NVIDIA Kumo Relational Client.
They assume that `graph` has already been defined:

```python
from kumo_relational_client import RelationalClient

def predict(query):
    with RelationalClient(url="http://localhost:8000") as client:
        return client.relational(graph).predict(query, run_mode="fast")
```

## Temporal Tasks (Forecast)

Temporal tasks use historical data from related tables to predict **future outcomes** over a **defined time horizon**.
Every temporal prediction has three components:

* **Target**: What to predict, expressed as an aggregation such as `SUM` or `COUNT`
* **Entity**: The row to predict for, identified by a table primary key
* **Horizon**: The future time window covered by the prediction

The general PQL pattern for temporal tasks is:

```sql
PREDICT <aggregation>(table.column, <start>, <end>, <unit>) FOR entity_table.pk=value
```

In this pattern, `<start>` and `<end>` define the future time window relative to "now."
The `<unit>` value specifies the time granularity, such as days, hours, or minutes.

### Forecast: Regression

Predict a **continuous numeric value** for an entity over a future time horizon.

**Use cases**: Demand forecasting, revenue prediction, and quantity estimation.

**Supported aggregations**: `SUM`, `AVG`, `COUNT`, `MAX`, `MIN`

```sql
-- Predict total revenue for item_id=42 in the next 30 days
PREDICT SUM(orders.price, 0, 30, days)
FOR items.item_id=42
```

```python
result = predict(
    "PREDICT SUM(orders.price, 0, 30, days) FOR items.item_id=42"
)
```

**Output**: A numeric value for each entity.
For quantile output, see [Configuration](/kumo-relational/user-guide/configure-and-scale/configuration#inference-configuration).

**Metrics**: `mae`, `mse`, `rmse`, `mape`, `smape`, and `r2`.

### Forecast: Binary Classification

Predict whether an entity **will or will not** experience an event within a future time window.
A **boolean condition** applied to an aggregation expression defines the two possible outcomes.

**Use cases**: Customer churn prediction and event occurrence prediction.

**Supported aggregations**: `SUM`, `AVG`, `COUNT`, `MAX`, `MIN` (with a boolean condition such as `= 0`, `> 100`)

```sql
-- Predict whether user_id=42 will make zero orders in the next 90 days (churn)
PREDICT COUNT(orders.*, 0, 90, days) = 0
FOR users.user_id=42
```

```python
result = predict(
    "PREDICT COUNT(orders.*, 0, 90, days) = 0 FOR users.user_id=42"
)
```

The boolean condition (`= 0`, `> 100`, etc.) on the aggregation makes this a binary classification task.

**Output**: A Boolean value (`True` or `False`) and a probability for each entity.

**Metrics**: `acc`, `auroc`, `auprc`, `ap`, `precision`, `recall`, and `f1`.

### Forecast: Multi-Class Classification

Predict which **class or state** an entity will belong to at a future point in time.
Use `FIRST()` to predict the first value that occurs in the window, or `LAST()` to predict the final value.

**Use cases**: Customer tier prediction, lifecycle stage prediction, and feature engagement.

**Supported aggregations**: `FIRST`, `LAST`

```sql
-- Predict what subscription tier user_id=42 will be in after 30 days
PREDICT FIRST(subscriptions.tier, 0, 30, days)
FOR users.user_id=42
```

```python
result = predict(
    "PREDICT FIRST(subscriptions.tier, 0, 30, days) FOR users.user_id=42"
)
```

**Output**: One row for each entity and class, with `CLASS`, `SCORE`, and `PREDICTED` fields.
`PREDICTED=True` marks the winning class.

**Metrics**: `acc`, `precision`, `recall`, `f1`, and `mrr`.

### Recommendations

Predict a **ranked list of items** an entity is most likely to interact with over a future time window.
Use `LIST_DISTINCT()` with `RANK TOP N` to return the top `N` recommended items.

**Use cases**: Product recommendations, content ranking, and next best action.

**Supported aggregations**: `LIST_DISTINCT` with `RANK TOP N`

```sql
-- Predict the top 10 items user_id=42 is most likely to order in the next 30 days
PREDICT LIST_DISTINCT(orders.item_id, 0, 30, days) RANK TOP 10
FOR users.user_id=42
```

```python
result = predict(
    "PREDICT LIST_DISTINCT(orders.item_id, 0, 30, days) RANK TOP 10 "
    "FOR users.user_id=42"
)
```

**Output**: A ranked list of item IDs for each entity.

**Metrics**: `map@k`, `ndcg@k`, `mrr@k`, `precision@k`, `recall@k`, `f1@k`, `hit_ratio@k`.

### Multi-Horizon Regression (Forecasting)

Predict a numeric value for an entity across **multiple future time steps**.
This task produces a time series of predictions.

**Use cases**: Multi-step demand forecasting and time series prediction.

**Supported aggregations**: `SUM`, `COUNT`, `COUNT_DISTINCT`

```sql
-- Predict weekly revenue for item_id=42 over the next 60 weeks
PREDICT SUM(orders.price, 0, 7, days) FORECAST 60 TIMEFRAMES
FOR items.item_id=42
```

```python
result = predict(
    "PREDICT SUM(orders.price, 0, 7, days) FORECAST 60 TIMEFRAMES "
    "FOR items.item_id=42"
)
```

The `FORECAST N TIMEFRAMES` clause tells Kumo Relational to produce `N` predictions, each separated by the time window specified in the aggregation, which is 7 days in this example.
Therefore, `FORECAST 60 TIMEFRAMES` with a 7-day window covers 60 × 7 = 420 days.

**Output**: Time-indexed numeric values, one for each horizon.
For quantile output, refer to [Configuration](/kumo-relational/user-guide/configure-and-scale/configuration#inference-configuration).

**Metrics**: `mae`, `mse`, `rmse`, `mape`, `smape`, and `r2`.

## Static Tasks

Static tasks infer **current or unknown entity attributes** from an entity's attributes and relationships.
A static prediction has no future time horizon.

Every static prediction has two components: the **target** attribute to infer and the **entity** to predict it for.

The general PQL pattern for static tasks is:

```sql
PREDICT table.column FOR entity_table.pk=value
```

### Static Regression

Infer a **continuous numeric attribute** of an entity.

**Use cases**: Age estimation, price imputation, and value scoring.

**Supported target type**: Numeric columns

```sql
-- Predict the age of user_id=42
PREDICT users.age
FOR users.user_id=42
```

```python
result = predict("PREDICT users.age FOR users.user_id=42")
```

**Output**: A numeric value for each entity.
For quantile output, see [Configuration](/kumo-relational/user-guide/configure-and-scale/configuration#inference-configuration).

**Metrics**: `mae`, `mse`, `rmse`, `mape`, `smape`, and `r2`.

### Static Binary Classification

Infer whether an entity belongs to **one of two classes** based on its attributes.

**Use cases**: Fraud detection and quality classification.

**Supported target type**: Boolean columns

```sql
-- Predict whether transaction_id=42 is fraudulent
PREDICT transactions.is_fraudulent
FOR transactions.transaction_id=42
```

```python
result = predict(
    "PREDICT transactions.is_fraudulent FOR transactions.transaction_id=42"
)
```

**Output**: A Boolean value (`True` or `False`) and a probability for each entity.

**Metrics**: `acc`, `auroc`, `auprc`, `ap`, `precision`, `recall`, and `f1`.

### Static Multi-Class Classification

Infer which **single class** an entity belongs to from a set of possible classes.

**Use cases**: Customer segmentation and category prediction.

**Supported target type**: Categorical columns

```sql
-- Predict the customer segment for customer_id=42
PREDICT customers.segment
FOR customers.customer_id=42
```

```python
result = predict(
    "PREDICT customers.segment FOR customers.customer_id=42"
)
```

**Output**: One row for each entity and class, with `CLASS`, `SCORE`, and `PREDICTED` fields.
`PREDICTED=True` marks the winning class.

**Metrics**: `acc`, `precision`, `recall`, `f1`, and `mrr`.

## Summary

Use this table to match the outcome you need with its PQL pattern and output type.

| Task Type                           | PQL Pattern                                                    | Output                | Category |
| ----------------------------------- | -------------------------------------------------------------- | --------------------- | -------- |
| Temporal Regression                 | `PREDICT SUM(t.col, 0, N, days) FOR ...`                       | Numeric               | Temporal |
| Temporal Binary Classification      | `PREDICT COUNT(t.*, 0, N, days) = 0 FOR ...`                   | Boolean + Probability | Temporal |
| Temporal Multi-Class Classification | `PREDICT FIRST(t.col, 0, N, days) FOR ...`                     | One row per class     | Temporal |
| Recommendations                     | `PREDICT LIST_DISTINCT(t.col, 0, N, days) RANK TOP K FOR ...`  | Ranked item list      | Temporal |
| Multi-Horizon Forecasting           | `PREDICT SUM(t.col, 0, N, days) FORECAST K TIMEFRAMES FOR ...` | Time-indexed numerics | Temporal |
| Static Regression                   | `PREDICT t.numeric_col FOR ...`                                | Numeric               | Static   |
| Static Binary Classification        | `PREDICT t.bool_col FOR ...`                                   | Boolean + Probability | Static   |
| Static Multi-Class                  | `PREDICT t.categorical_col FOR ...`                            | One row per class     | Static   |