Prediction Results | NVIDIA Structured Data and Graph Models

client.relational(graph).predict() returns Kumo Relational results as a pandas DataFrame. The ENTITY field maps each result row to an input entity. Temporal predictions can also include ANCHOR_TIMESTAMP. Join downstream data by using these identifier fields instead of relying on row position.

from kumo_relational_client import RelationalClient
with RelationalClient(url="http://localhost:8000") as client:
    result = client.relational(graph).predict(query, run_mode="fast")
print(result.columns)
print(result.head())

Result fields

The fields that are present depend on the prediction task and the requested outputs.

Field	When present	Description
`ENTITY`	All Kumo Relational results	Entity identifier from the prediction input.
`ANCHOR_TIMESTAMP`	When an anchor time is available	Prediction anchor time associated with the input.
`PREDICTION`	Binary classification and regression results	Predicted Boolean or numeric value.
`<CLASS>_PROB`	Binary-classification probabilities	Probability for the named Boolean class, such as `TRUE_PROB`.
`CLASS`	Multiclass and link-prediction results	Class value or ranked-candidate identifier. The SDK preserves the target or identifier dtype.
`SCORE`	Multiclass and link-prediction results	Score for the class or candidate in the same row.
`PREDICTED`	Multiclass results	`True` for the winning class and `False` for the other candidate classes.
`FORECAST_STEP`	Forecast results	One-based sequence number of the forecast period.
`SCORES`	Other score outputs	Ordered score values returned by the model.
`Q_<Level>`	Quantile outputs	Predicted value at the specified quantile level.
`EMBEDDINGS`	When embeddings are requested	Model embedding values.

Do not assume that every task returns every field or one row per input entity. Binary classification and regression return one row per entity. Multiclass classification returns one row per entity per class, temporal link prediction returns one row per candidate, and forecasting returns one row per forecast timeframe. Inspect the DataFrame columns or the NIM model capabilities before processing optional outputs.

The Python SDK DataFrame uses uppercase PREDICTION. The NIM REST response uses lowercase prediction in each prediction item. Refer to NIM REST API when working with the wire format directly.

Illustrative shapes

Scalar regression:

   ENTITY      ANCHOR_TIMESTAMP  PREDICTION
0      42  2025-01-01T00:00:00Z      128.40

Boolean classification:

   ENTITY  PREDICTION  FALSE_PROB  TRUE_PROB
0      42        True        0.21       0.79

Multiclass classification:

   ENTITY      ANCHOR_TIMESTAMP       CLASS  SCORE  PREDICTED
0      42  2025-01-01T00:00:00Z  enterprise   0.73       True
1      42  2025-01-01T00:00:00Z      public   0.15      False
2      42  2025-01-01T00:00:00Z       small   0.12      False

Filter the winning row for each entity with result[result["PREDICTED"]]. Do not coerce CLASS to a string; it preserves the target column’s dtype.

Forecasting:

   ENTITY      ANCHOR_TIMESTAMP  PREDICTION  FORECAST_STEP
0      42  2025-01-01T00:00:00Z      128.40              1
1      42  2025-01-01T00:00:00Z      134.75              2
2      42  2025-01-01T00:00:00Z      141.20              3

A forecasting result contains one row per entity per forecast step. FORECAST_STEP is one-based.

Temporal link prediction with three ranked candidates:

   ENTITY      ANCHOR_TIMESTAMP  CLASS  SCORE
0      42  2025-01-01T00:00:00Z  sku-7   0.91
1      42  2025-01-01T00:00:00Z  sku-3   0.84
2      42  2025-01-01T00:00:00Z  sku-9   0.72

A RANK TOP 3 link-prediction query returns three rows per entity, ordered from the highest-scoring candidate to the lowest.

These examples show only the column structure. The values depend on the query and the deployed release.

Classification probabilities

Binary-classification probabilities are expanded into separate columns, such as TRUE_PROB and FALSE_PROB. Multiclass classification instead returns one row per class with CLASS, SCORE, and PREDICTED.

Ranked results

The SDK expands ranked outputs to one row per candidate. CLASS contains the candidate identifier and SCORE contains its ranking score. Preserve the returned row order when presenting candidates for the same entity.

Quantiles and forecasts

Quantile outputs use columns prefixed with Q_. The exact quantile levels depend on the requested inference output. A forecast returns one row per timeframe and uses FORECAST_STEP to identify the one-based sequence.

Explanations

When explain=True, predict() returns an Explanation object instead of a bare DataFrame. Its prediction attribute contains the prediction DataFrame, details contains structured attribution, and summary contains natural-language text when the backend provides it. See Prediction Explainability.