> 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 produces a sequence of predictions for one entity across consecutive future time windows.
Use it when you need a value for each future period, such as weekly order totals, rather than one aggregate value for the entire forecast horizon.

## Minimal forecast

The example requires a validated `graph` and a reachable Kumo Relational NIM endpoint.

```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:
    model = client.relational(graph)
    result = model.predict(query, run_mode="fast")
```

This Predictive Query Language (PQL) query requests eight consecutive predictions for account `42`.
Each timeframe is one seven-day window, so the result covers eight adjacent seven-day periods.
The `fast` run mode limits the prediction context and graph neighborhood size to reduce inference time.

## Requirements and limits

A forecast must meet these requirements:

* Predict one entity per request.
* Use a time-windowed aggregation with an explicit window length and time unit.
* Request no more than 10,000 timeframes.
* Provide enough chronologically ordered history before the anchor time, the timestamp where the forecast begins, to represent the pattern.
* Connect the target and entity tables through valid relationships 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 each later row advances by another seven days.
For every window, the start boundary is excluded and the end boundary is included.

## Anchor time and lagged targets

```python
import pandas as pd

with RelationalClient(url="http://localhost:8000") as client:
    model = client.relational(graph)
    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 prediction interface returned by `client.relational(graph)`.

* `anchor_time` sets the beginning of the forecast.
* `lag_timesteps` includes previous target windows as additional model inputs.
* `use_prediction_time` includes the prediction timestamp as a model input.

Evaluate these options with historical backtests, which simulate past forecasts against known outcomes, because they do not improve results for every dataset.

## Results

The SDK returns one prediction row per timeframe in a pandas DataFrame.
Use these columns to interpret each row:

* `PREDICTION` contains the primary predicted value.
* `ENTITY` identifies the requested entity.
* `ANCHOR_TIMESTAMP` appears when the request specifies an anchor time.
* `FORECAST_STEP` identifies the timeframe by its one-based position in the forecast.

If the inference configuration requests quantiles, the output also includes `Q_<Level>` columns.

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

Refer to [Prediction Results](/kumo-relational/user-guide/work-with-prediction-results/prediction-results) for the complete result schema.

## 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      | Use `fast` run mode or request fewer columns, relationships, or timeframes.                       |
| Poor backtest accuracy    | Recheck window boundaries, leakage, seasonality, and lag settings before increasing context size. |