Data Requirements

Kumo Relational operates on related entity tables and event tables. Prepare the source data before building a schema so that keys, timestamps, and relationships have consistent values and physical types.

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 building the schema.
• Task-relevant history: Include events that occur before the prediction anchor time and enough labeled history to represent the task.
• Clear column meaning: Assign semantic types to distinguish identifiers, numerical measures, categories, text, timestamps, and sequences.

Schema.check_consistent() can detect invalid metadata, but it cannot determine whether a relationship, timestamp, or historical window is appropriate for your prediction task. Review the inferred metadata before running inference.

Choose a data location

Schema.from_source() describes tables that stay where they are: no table is read in full, though building the schema does query the source for column metadata and a small row preview per table. Only materialize() samples the rows one prediction actually needs, with SQL. Use from_source() for tables too large to fit in application memory, or to avoid reading a whole warehouse table for a small prediction. See Build a Schema and the connector pages for both routes.

Prepare example tables

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

For a table built from Schema.from_source(), the engine runs the equivalent check against the source instead, as one statement per table; pass check_keys=False to skip it when the cost matters and the key is already trusted.

Next, review Data Types and Semantic Types, choose the appropriate time column, and follow the Data Preparation Best Practices. After the source data is ready, build a schema.