Forecasting

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 assumes that you already have graph, a Kumo relational graph that maps your tables and their relationships, and a running Kumo Relational NVIDIA Inference Microservice (NIM), the service that executes predictions.

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:

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

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.

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 for the current mapping.

Troubleshooting