> This page is for Structured Data Models. > 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. # Kumo Relational > Classification and regression across tables linked by keys, in context. Kumo Relational extends in-context learning from one table to related tables. It predicts a target for task rows using the rows linked to them through primary and foreign keys, without flattening the data into one table. ## At a Glance | Property | Value | | ------------ | ------------------------------------------------------------------------------------------------------------- | | Class | `sdm.models.KumoRelational` | | Tasks | Classification and regression (999 quantiles) | | Inputs | Task rows (`x_context`, `y_context`, `x_query`) plus `RelatedTables` for context and query | | Parameters | 29.93M to 30.94M | | Weights | [nvidia/Kumo-Relational](https://huggingface.co/nvidia/Kumo-Relational), OpenMDW-1.1 with BSD-3-Clause notice | | Available in | SDM 0.2.1 and later | | Reference | [KumoRFM-2: Scaling Foundation Models for Relational Learning](https://arxiv.org/abs/2604.12596) | ## When to Use It * Your prediction target is about an entity (a user, an item, a patient) and the evidence is in other tables, such as orders or visits. * You want to avoid hand-built aggregate features. * Choose [Kumo Tabular](/sdgm/structured-data-models/models/kumo-tabular) when all features already sit in one row. ## How It Works ![Kumo Relational in three panels: (a) task rows linked to related Users, Orders, and Items tables; (b) row and column attention within each table; (c) inter-table message passing and attention across samples.](/sdgm/_fern-files/nvidia-sdgm.docs.buildwithfern.com/96b852c1c3fc9377257d21193e494360ca89593c16b75c64b5452b2c6f7cc28b/_dot_dot_/images/structured-data-models/kumo_relational_light.svg) ![Kumo Relational in three panels: (a) task rows linked to related Users, Orders, and Items tables; (b) row and column attention within each table; (c) inter-table message passing and attention across samples.](/sdgm/_fern-files/nvidia-sdgm.docs.buildwithfern.com/79304e0adcb4aa1f7835d79c4e9c194bf737f5168ba813010718b0037a57fbb9/_dot_dot_/images/structured-data-models/kumo_relational_dark.svg) 1. **Intra-table row embeddings.** Each related table is embedded with a TabICLv2-style row embedding stack. Context targets are distributed over the relational graph. 2. **Inter-table message passing.** A schema-agnostic GNN exchanges row embeddings along the relationships for `num_hops` rounds, then reads out the rows linked to the task table. 3. **In-context learning.** Query task rows attend to labeled context task rows to produce class logits or quantiles. ## Describe Your Tables A `RelatedTables` object has three parts: * `tables`: a name for each related table and its `TableTensor`. * `relationships`: key joins between tables. Single or composite keys. * `task_links`: exactly one entry point from task rows into a related table. ![Related tables and their keys: task rows with a churn target link by user\_id to a users table through a dashed task link. Views and orders reference users by user\_id and items by item\_id through solid relationship links.](/sdgm/_fern-files/nvidia-sdgm.docs.buildwithfern.com/0b2d14aedb2633f2d7f5d0df3f3c45677b827258cd0c2f1fefbc7ff7d40f55f0/_dot_dot_/images/structured-data-models/relational_schema_light.svg) ![Related tables and their keys: task rows with a churn target link by user\_id to a users table through a dashed task link. Views and orders reference users by user\_id and items by item\_id through solid relationship links.](/sdgm/_fern-files/nvidia-sdgm.docs.buildwithfern.com/5ded0208b9f1792569ae2a876abfa0105ae980b183f3b0f92efd7a662e67decc/_dot_dot_/images/structured-data-models/relational_schema_dark.svg) Columns with the `id` semantic type define relationships and are not used as features. ## Example This toy example predicts churn for two users from two labeled users and their orders. ```python import torch import sdm task_table = sdm.TableTensor.from_columns( {"user_id": [0, 1, 2, 3], "churn": [True, False, True, False]}, stypes={"user_id": "id", "churn": "categorical"}, ) related = sdm.RelatedTables( tables={ "users": sdm.TableTensor.from_columns( {"user_id": [0, 1, 2, 3], "age": [42, 23, 31, 26]}, stypes={"user_id": "id", "age": "numerical"}, ), "orders": sdm.TableTensor.from_columns( {"user_id": [0, 0, 1, 3, 3, 3], "amount": [9.99, 4.99, 12.99, 7.99, 3.99, 5.99]}, stypes={"user_id": "id", "amount": "numerical"}, ), }, relationships=[{"left_table": "orders", "left_columns": "user_id", "right_table": "users", "right_columns": "user_id"}], task_links=[{"task_columns": "user_id", "table": "users", "table_columns": "user_id"}], ) # Context rows (users 0, 1) carry labels; query rows (users 2, 3) do not. related_context = related.replace_tables({ "users": related.tables["users"][:2], "orders": related.tables["orders"][:3]}) related_query = related.replace_tables({ "users": related.tables["users"][2:], "orders": related.tables["orders"][3:]}) model = sdm.models.KumoRelational(task="classification") probs = model( x_context=task_table[:2].drop_columns("churn"), y_context=task_table[:2, "churn"], x_query=task_table[2:].drop_columns("churn"), related_context_tables=related_context, related_query_tables=related_query, num_hops=1, generator=torch.Generator().manual_seed(0), ) print(probs.to_pandas()) ``` **`Expected output`** ```text title="Expected output" False True 0 0.321723 0.678277 1 0.203182 0.796818 ``` With two labeled users, the probabilities only show that the pipeline runs. Real tasks need many more context rows. ## Work with Real Data For real datasets, use SDM's subgraph samplers to build `RelatedTables` for each batch of task rows, with CPU (`pyg-lib`) or CUDA (`cugraph`) backends. When two task rows refer to the same entity at different times, add a task ID to composite keys so each row only sees records available at its prediction time. The [RelBench example](https://github.com/NVIDIA/structured-data-models/tree/main/examples/relational/relbench) in the SDM repository shows this end to end. From that example's directory, run: ```bash python main.py --dataset=rel-f1 --task=driver-dnf ``` ## Inputs and Limits * Pass `related_context_tables` and `related_query_tables` together; the model requires related tables. * Exactly one task link to an entity table. * Tables must be two-dimensional. * One target column per call. ## Run as a Service The Kumo Relational NIM accepts predictive queries through the [Structured Data Models Client](/sdgm/client/overview). Use SDM when you want the model in your own Python process and full control over sampling. ## Learn More * [KumoRelational API reference](https://nvidia.github.io/structured-data-models/api/generated/sdm.models.KumoRelational.html) * [Relational context guide](https://nvidia.github.io/structured-data-models/icl.html#relational-context) * [Hugging Face model card](https://huggingface.co/nvidia/Kumo-Relational) * [KumoRFM-2 paper](https://arxiv.org/abs/2604.12596)