How Kumo Relational Works
Kumo Relational is a pre-trained relational foundation model. Instead of training a task-specific model, you provide related tables, describe the prediction task in Predictive Query Language (PQL), and run inference against a Kumo Relational NVIDIA NIM.
From tables to predictions
sdm-client uses table metadata and relationships to construct a Schema — the same type it uses for a single table, since one table with no relationships is the degenerate case of the same shape. For each prediction, PredictiveQuery.materialize() selects relevant historical context, samples each entity’s neighborhood, and encodes the result as a Request. SDMClient.predict() sends it to the configured NIM and returns a PredictionResult.
The materialized request context is sent to the NIM endpoint. Data-boundary and security controls depend on where you deploy the NIM; use HTTPS whenever an API key or sensitive data crosses a network boundary.
A Schema can describe tables already in memory (Schema.from_data) or tables left where they live — a warehouse or database, sampled with SQL at prediction time (Schema.from_source). See Build a Relational Graph.
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 labeled examples — the context, in sdm-client’s terms — together with the entity to predict.
For the standard PQL workflow:
- The query defines the target, prediction entity, and, for a temporal task, the prediction horizon.
materialize()constructs labeled context examples from historical database states.- For each context example and prediction entity, Kumo Relational samples related records visible as of that example’s anchor timestamp.
- The relational graph transformer reasons across table rows, columns, primary–foreign key relationships, and context examples to produce the prediction.
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.
Some deployments serve only classification and regression — the client builds the rest
A kumo-relational deployment can be configured to natively answer only classification and regression questions. A ranking or a multi-step forecast is neither, so for that narrower deployment, sdm-client asks each as several classification or regression questions and assembles the answers:
- Ranking (
RANK TOP K) is decomposed into one classification call per candidate — “will this entity reach this one?” — then ordered by confidence. See Prediction Types. - Forecasting (
FORECAST N TIMEFRAMES) is decomposed into one regression call per step. See Forecasting.
Both use several round trips automatically; you still call materialize() and predict() once. See Limits for how many calls each can make.