Time Columns | NVIDIA Kumo

Kumo Relational uses table-level time metadata to construct context as it existed at a prediction boundary. A column can have a timestamp data type and the timestamp semantic type without being designated as the table’s time_column.

time_column identifies when a row became available to the prediction workflow. Set it only when the column represents the table’s own timeline. An administrative timestamp such as a last-modified date does not necessarily serve that role.

Choose the appropriate column

Table pattern	`time_column`
Event or transaction table	The event timestamp
Entity or lookup table	The entity creation timestamp, when available; otherwise unset

For example, an order table can use its order timestamp as time_column.

sdm_client.Table has no end_time_column. If your data models row validity with a start and an end (a versioned or validity-tracked table), only the start can be declared as the table’s timeline today; there is no supported way to also declare when a row stopped being valid.

How inference chooses a time column

Inference reads the whole table and applies a rule, not just a name match. It will not take:

a timestamp column that is empty in more than half the rows;
one holding a single value everywhere it holds any, unless the table has one row;
one named for when a row was loaded or synced;
a date of birth;
a last-edit stamp such as ModifiedDate, on a table another table links to (it can still be taken on a table nothing links to, if it is the only timestamp candidate left).

Of several remaining candidates, a column named like created/created_at wins; otherwise, the candidate whose values start earliest is chosen, with placeholder dates such as 1900-01-01 and 1970-01-01 ignored. A column that cannot be read stays a candidate rather than being discarded.

Configure the time column

Build the schema, inspect the inferred metadata, and correct each table as needed:

from sdm_client import Schema
schema = Schema.from_data({"customers": customers, "orders": orders})
schema["orders"].time_column = "order_time"

Schema.from_data() and Schema.from_source() both take time_columns= to set them at build time:

schema = Schema.from_data(
    {"customers": customers, "orders": orders},
    time_columns={"orders": "order_time"},
)

Pass time_columns={"orders": None} to say a table has no time column, overriding inference, on either builder.

Setting time_column also marks that column’s semantic type as timestamp; the SDK rejects an incompatible physical data type. A table’s primary key and time column must be different columns.

After making changes, call schema.check_consistent(). See Configure Table Metadata for the complete metadata workflow.

Behavior during sampling

time_column participates in temporal neighbor sampling, so a future row relative to the prediction anchor is not sampled into context. The anchor_time prediction setting selects the reference time used for a request — see Set the anchor time.

Review checklist

The time column represents when a row became available, not merely when it was edited.
The source column uses a consistent, unambiguous datetime representation.
The same column is not assigned as both the primary key and the time column.
The schema is checked with schema.check_consistent() after any correction.