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

# Forecasting

> Run single-entity multi-timeframe forecasts with Kumo Relational

Forecasting repeats a temporal target across consecutive future windows. Use forecasting when you need a sequence of predictions for one entity rather than a single aggregate over the entire horizon.

## Minimal forecast

```python
from kumo_relational_client import RelationalClient

query = """
PREDICT SUM(orders.amount, 0, 7, days)
FORECAST 8 TIMEFRAMES
FOR accounts.account_id=42
"""

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

This query requests eight consecutive predictions for seven-day windows for account `42`.

## Requirements and limits

* Forecast predictions for one entity per request.
* Use a temporal aggregation with an explicit window and unit.
* Request no more than 10,000 timeframes.
* Provide enough ordered history before the anchor time to represent the pattern.
* Ensure that the target and entity have a valid relationship in the graph.

Supported target forms depend on the current Kumo Relational validator and deployed NIM release. Start with `SUM`, `COUNT`, or `COUNT_DISTINCT`. Verify support for other aggregations against the capabilities of the deployed release.

## Window semantics

For the following target:

```text
PREDICT SUM(orders.amount, 0, 7, days)
FORECAST 8 TIMEFRAMES
```

The first forecast row covers the first seven-day window after the anchor time. The second row covers the next seven-day window, and so on. The start boundary is excluded, and the end boundary is included.

## Anchor time and lagged targets

```python
import pandas as pd

result = model.predict(
    query,
    run_mode="normal",
    anchor_time=pd.Timestamp("2025-01-01T00:00:00Z"),
    lag_timesteps=3,
    use_prediction_time=True,
)
```

Here, `model` is the graph-bound handle returned by `client.relational(graph)`.

* `anchor_time` sets the beginning of the forecast.
* `lag_timesteps` supplies previous target windows as additional context.
* `use_prediction_time` supplies the prediction timestamp as a feature.

Evaluate these options with historical backtests because they do not improve results for every dataset.

## Results

The current SDK maps the primary predicted value to `PREDICTION` and the requested entity to `ENTITY`. When the request specifies an anchor time, each result row also includes `ANCHOR_TIMESTAMP`. A forecast returns one prediction row per timeframe and identifies its one-based position by using `FORECAST_STEP`. When requested through the inference configuration, quantile output adds `Q_<Level>` columns.

```python
print(result.columns)
print(
    result[
        ["ENTITY", "ANCHOR_TIMESTAMP", "FORECAST_STEP", "PREDICTION"]
    ].head()
)
```

Do not rely on the legacy `TARGET_PRED` field. Refer to [Prediction Results](/rfm/prediction-results) for the current mapping.

## Troubleshooting

| Symptom                   | Check                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| Forecast validation fails | Confirm a single explicit entity, supported aggregation, time column, and timeframe count.        |
| Too little history        | Move the anchor later or include more pre-anchor events.                                          |
| Request is too large      | Reduce run mode, columns, relationships, or timeframe count.                                      |
| Poor backtest accuracy    | Recheck window boundaries, leakage, seasonality, and lag settings before increasing context size. |