Data Requirements

Kumo Relational builds a graph from related tables to represent the entities in your data and the events that connect them. An entity table describes objects such as customers or products, while an event table records interactions such as orders. Prepare these tables before creating the graph so that Kumo can join records correctly and use only the history available at prediction time.

Required table characteristics

• Stable entity keys: Each entity table must have a non-null, unique primary key.
• Consistent foreign keys: Relationship columns must use compatible values and types across tables.
• Usable timestamps: Event tables must identify when each event occurred. Convert source values to a supported timestamp type before constructing the graph.
• Task-relevant history: Include events that occur before the prediction anchor time, which is the point in time when Kumo makes each prediction. Include enough labeled history to represent the task.
• Clear column meaning: Assign semantic types, which tell Kumo how to interpret each column, to distinguish identifiers, numerical measures, categories, text, timestamps, and sequences.

Choose a data location

Choose a location based on where your prepared data already lives and how you want Kumo to access it.

For databases and warehouses, refer to the corresponding page under Connect Data Sources for information about permissions, connection parameters, and source-specific preparation. Connector-backed graphs query and sample data from the source instead of loading every source table into a DataFrame.

Prepare example tables

The following example creates two entity tables, customers and products, and one event table, orders. The key columns use matching physical types so that Kumo can connect each order to its customer and product.

import pandas as pd
customers = pd.DataFrame({
    "customer_id": pd.Series([1, 2, 3], dtype="int64"),
    "segment": pd.Series(["small", "enterprise", "small"], dtype="string"),
    "notes": pd.Series(["prefers email", "", "new account"], dtype="string"),
    "signup_time": pd.to_datetime(["2024-01-01", "2024-02-15", "2024-03-20"]),
})
orders = pd.DataFrame({
    "order_id": pd.Series([101, 102, 103], dtype="int64"),
    "customer_id": pd.Series([1, 1, 2], dtype="int64"),
    "product_id": pd.Series([501, 502, 501], dtype="int64"),
    "amount": pd.Series([20.0, 35.0, 50.0], dtype="float64"),
    "order_time": pd.to_datetime(["2024-04-01", "2024-04-08", "2024-04-10"]),
})
products = pd.DataFrame({
    "product_id": pd.Series([501, 502], dtype="int64"),
    "product_name": pd.Series(["Basic", "Premium"], dtype="string"),
})

Before continuing, confirm that primary-key candidates are non-null and unique, and that related key columns use compatible physical types.

assert customers["customer_id"].notna().all()
assert customers["customer_id"].is_unique
assert orders["order_id"].notna().all()
assert orders["order_id"].is_unique
assert products["product_id"].notna().all()
assert products["product_id"].is_unique
assert orders["customer_id"].dtype == customers["customer_id"].dtype
assert orders["product_id"].dtype == products["product_id"].dtype

Kumo also accepts unsigned integer columns. During request preparation, nullable integer keys and identifiers larger than JavaScript’s safe-integer range retain their integer identity. Timezone-aware timestamps are converted to UTC rather than having their offsets discarded.

Next, review Data Types and Semantic Types, choose the appropriate Time and End-Time Columns, and follow the Data Preparation Best Practices. After the source data is ready, create a graph.