Define Relationships | NVIDIA Structured Data and Graph Models

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:

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:

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():

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:

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:

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

graph.print_links()

Next, validate the complete graph.