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

# How Kumo Relational Works

> Understand how Kumo Relational turns relational context and PQL into predictions through NVIDIA NIM

A prediction request combines a task, the entities to score, and relevant
historical data. The client prepares this context; the Kumo Relational NIM runs
the model on it. For model capabilities, see the
[NIM Overview](/kumo-relational/about-kumo-relational/overview).

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

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

The relational engine samples records through the configured data connector.

> **Note**
>
> The records selected for a request are sent to the NIM endpoint.
> Data-boundary and security controls depend on where you deploy the NIM and connector; use HTTPS whenever an API key or sensitive data crosses a network boundary.

## 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. The relational engine constructs labeled context examples from historical database states.
3. For each context example and prediction entity, the relational engine 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.

![Kumo Relational in-context learning flow from a predictive query and relational database to context samples, prediction, and explanations](/sdgm/_fern-img/7d2d8d6d946670da4016e105ed2d73d3f7416110f07e1b3105340c26bd1701ec.webp)

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()`](/kumo-relational/user-guide/make-predictions/custom-context).

For more about the model architecture and pre-training approach, see the [Kumo Relational paper](https://arxiv.org/abs/2604.12596).

## Apply These Concepts

* [Define Relationships](/kumo-relational/user-guide/build-a-relational-graph/graph-definitions)
  to control which records connect in the graph.
* [Time and End-Time Columns](/kumo-relational/user-guide/prepare-data/time-columns)
  explains how table metadata controls the history available at an anchor time.
* [Configuration](/kumo-relational/user-guide/configure-and-scale/configuration)
  describes neighborhood sampling and prediction settings.