> This page is for Structured Data Models Client.

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

# Define Relationships

> Review and correct relationships between Kumo Relational schema tables

Relationships connect foreign keys in event or junction tables to primary keys in entity tables. Kumo Relational uses these relationships to sample relational context for a prediction.

Continue with the schema and table metadata configured on the preceding pages.

## Inspect inferred relationships

`Schema.from_data()` infers relationships by matching a column to a primary key of the same name — deliberately conservative, since a wrong link changes what the model is shown and is harder to notice than a missing one. `Schema.from_source()` prefers the foreign-key constraints the catalog declares, and falls back to the same name-matching inference where it declares none. Inspect the result before running predictions:

```python
print(schema.relationships)
```

For the `customers`, `orders`, and `products` example, confirm that the schema contains the following relationships:

| Source table | Foreign key   | Target table | Target key    |
| ------------ | ------------- | ------------ | ------------- |
| `orders`     | `customer_id` | `customers`  | `customer_id` |
| `orders`     | `product_id`  | `products`   | `product_id`  |

## Correct a relationship

`Relationship` is a plain dataclass. If inference misses a relationship, add it explicitly:

```python
from sdm_client import Relationship

schema.relationships.append(
    Relationship(
        source_table="orders",
        source_column="customer_id",
        target_table="customers",
        target_column="customer_id",
    )
)
```

If inference creates an incorrect relationship, remove it before adding the intended one:

```python
schema.relationships = [
    link for link in schema.relationships
    if not (link.source_table == "orders" and link.source_column == "customer_id"
            and link.target_table == "products")
]
schema.relationships.append(
    Relationship("orders", "customer_id", "customers", "customer_id")
)
```

Use consistent primary-key and foreign-key names whenever possible. For example, prefer `customer_id` in both `customers` and `orders` instead of mixing names such as `id`, `customer_id`, and `account_id` for the same entity — a name shared by more than one table's primary key is ambiguous and links nothing.

Composite relationships are supported. A composite foreign key must reference the full composite primary key, with corresponding columns supplied in the same order and with compatible physical types:

```python
schema["customers"].primary_key = ("customer_id", "region")

schema.relationships.append(
    Relationship(
        source_table="orders",
        source_column=("customer_id", "region"),
        target_table="customers",
        target_column=("customer_id", "region"),
    )
)
```

A relationship can only point at a table's declared primary key, and a table with a composite key can only be the target of a relationship whose source columns match it component for component.

> **Warning**
>
> For a schema built over a semantic model (`source.semantic_model(...)`), passing `relationships=` to `from_source()` **replaces** the model's own joins rather than adding to them. To keep the model's relationships and add one more, read `schema.relationships` after building and append to it, as shown above, rather than passing `relationships=` to `from_source()`.

## Model one-to-many relationships

Kumo Relational schema relationships represent primary-key-to-foreign-key relationships. The target table contains the unique primary key, and the source table can contain that foreign-key value across multiple rows.

For many-to-many relationships, prepare a junction table that converts the relationship into two one-to-many relationships. For example, an `order_items` table can relate `orders` and `products` through `order_id` and `product_id`. Refer to [Data Preparation Best Practices](/sdgm/kumo-relational/user-guide/prepare-data/best-practices) for the junction-table pattern.

## Relationship checklist

* Every foreign key points to the intended entity table.
* The referenced target column is that table's primary key.
* Source and target key values use compatible physical types.
* Each relationship has business meaning, rather than merely sharing a column name.
* The schema contains the paths needed by the predictive queries you plan to run.

After making corrections, inspect the relationships again:

```python
print(schema.relationships)
```

Next, [check the complete schema](/sdgm/kumo-relational/user-guide/build-a-relational-graph/graph-validation).