How Kumo Relational Works

Kumo Relational is a pre-trained AI model that makes predictions from related database tables without requiring you to train a separate model for each task. You describe what to predict and for which entities in Predictive Query Language (PQL), then run the request against a Kumo Relational NVIDIA NIM, a packaged service that hosts the model for inference.

From tables to predictions

The SDK uses table metadata and primary-key and foreign-key relationships to construct a relational graph, which represents rows as connected data. For each prediction request, the SDK selects relevant historical records from the graph, converts the query and records into model input, sends that input to the configured NIM, and returns the predictions as a pandas DataFrame.

related tables → relational graph → PQL task → sampled context → Kumo Relational NIM → predictions

A connector reads and samples the required records from your configured data source.

How in-context learning works

In-context learning lets a pre-trained model adapt to a prediction task without updating its model weights. Instead of training a new model for each task, Kumo Relational receives context examples, historical examples whose outcomes are already known, together with the entity to predict.

For the standard PQL workflow:

1. The query defines the target outcome, the entity to predict, and, for a temporal task, how far into the future to predict.
2. Kumo Relational constructs labeled context examples from historical database states.
3. For each context example and prediction entity, Kumo Relational samples related records that were available at the example’s anchor timestamp, the point in time from which the prediction is made.
4. The relational graph transformer, the model architecture that processes connected tabular data, uses table rows, columns, key relationships, and context examples to produce the prediction in one inference pass.

The context examples show the model how the target relates to the surrounding relational data. Because their timestamps define what information was available at each point in time, Kumo Relational can construct temporal context without exposing future events to the model. You can also provide labeled context examples directly with predict_task().

For more about the model architecture and pre-training approach, see the Kumo Relational paper.

Standard workflow

If you are new to Kumo Relational, start with installation and the quickstart, then use the remaining guides as you build and interpret your own prediction workflow.