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

# Data Requirements

> Prepare relational tables, keys, timestamps, and history for Kumo Relational

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

| Data location                     | Build the schema with                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------------------------ |
| pandas (already in memory)        | `Schema.from_data()`                                                                             |
| SQLite, DuckDB                    | `Schema.from_data()` after `sdm_connectors.read()`, or `Schema.from_source()` to sample in place |
| PostgreSQL, Databricks Lakebase   | `Schema.from_source()` — tables stay in the database                                             |
| Snowflake, Databricks (warehouse) | `Schema.from_source()` — tables stay in the warehouse                                            |

`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](/sdgm/kumo-relational/user-guide/build-a-relational-graph/graph-creation) and the connector pages for both routes.

## Prepare example tables

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

```python
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](/sdgm/kumo-relational/user-guide/prepare-data/data-types), choose the appropriate [time column](/sdgm/kumo-relational/user-guide/prepare-data/time-columns), and follow the [Data Preparation Best Practices](/sdgm/kumo-relational/user-guide/prepare-data/best-practices). After the source data is ready, [build a schema](/sdgm/kumo-relational/user-guide/build-a-relational-graph/graph-creation).