> 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 tables in a Kumo Relational graph

In a Kumo Relational graph, a relationship tells Kumo how rows in two tables connect.
It maps a foreign key in a source table to the primary key in a destination table.
The source is often an event table that records activity, such as orders, or a junction table that connects entities.
The destination is typically an entity table with one row per object, such as a customer or product.
Kumo follows these relationships to gather related records that provide context for a prediction.

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

## Inspect inferred relationships

The `Graph.from_*()` methods used to create a graph infer relationships from keys, column names, and compatible data types.
Before running predictions, confirm that each inferred relationship matches the meaning of your data:

```python
graph.print_links()
```

The source table contains the foreign key, and the destination table contains the primary key that it references.
For the `customers`, `orders`, and `products` example, confirm that the graph contains these relationships:

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

You can also inspect individual edges:

```python
for edge in graph.edges:
    print(f"{edge.src_table}.{edge.fkey} -> {edge.dst_table}")
```

## Correct a relationship

If inference misses a relationship, add it explicitly with `graph.link()`:

```python
graph.link(
    src_table="orders",
    fkey="customer_id",
    dst_table="customers",
)
```

If inference creates an incorrect relationship, remove it with `graph.unlink()` before adding the intended relationship:

```python
graph.unlink(
    src_table="orders",
    fkey="customer_id",
    dst_table="products",
)
graph.link(
    src_table="orders",
    fkey="customer_id",
    dst_table="customers",
)
```

Consistent primary-key and foreign-key names make automatic inference more reliable.
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.

#### Define a relationship with a composite key

A composite key uses multiple columns together to identify a row.
For a composite relationship, the foreign key must reference every column in the composite primary key.
Supply the corresponding columns in the same order and with compatible physical types:

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

graph.link(
    src_table="orders",
    fkey=("customer_id", "region"),
    dst_table="customers",
)
```

The order of `fkey` must match the destination table's `primary_key` order.
A one-column foreign key cannot reference only part of a composite identity.

## Model one-to-many relationships

Kumo Relational graph edges represent primary-key-to-foreign-key relationships.
The destination table contains the unique primary key, while the source table can repeat that value as a foreign key across multiple rows.
For example, one row in `customers` can connect to many rows in `orders` that contain the same `customer_id`.

For a many-to-many relationship, prepare a junction table that converts it into two one-to-many relationships.
For example, an `order_items` junction table can relate `orders` and `products` through `order_id` and `product_id`.
Refer to [Data Preparation Best Practices](/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 destination column is a primary key.
* Source and destination key values use compatible physical types.
* Each relationship has business meaning, rather than merely sharing a column name.
* The graph contains the paths needed by the predictive queries you plan to run.

After making corrections, inspect the relationships again:

```python
graph.print_links()
```

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