Time and End-Time Columns

Time and end-time columns tell Kumo Relational when each row became available and, when relevant, when it stopped being valid. Kumo Relational uses this metadata to build prediction context that contains only information available at the prediction’s reference time, called the anchor time.

A column can have a datetime data type and the timestamp semantic type without representing the table’s timeline. The semantic type tells Kumo Relational how to interpret the column’s values, while time_column and end_time_column give the column a specific role in temporal sampling.

time_column identifies when a row became available to the prediction workflow.
end_time_column identifies when a row stopped being valid.

Set these fields only when the columns represent the table’s timeline. Administrative timestamps such as a last-modified date do not necessarily serve that role.

Choose the appropriate columns

Table pattern	`time_column`	`end_time_column`
Event or transaction table	The event timestamp	Usually unset
Versioned or validity-tracked table	The validity start timestamp	The validity end timestamp
Entity or lookup table	The entity creation timestamp, when available; otherwise unset	Usually unset

For example, an order table can use its order timestamp as time_column. A subscription-history table can use valid_from as time_column and valid_to as end_time_column. A null end time represents an open-ended interval.

Configure table metadata

After you create the graph, inspect the inferred metadata with graph.print_metadata() and correct each table as needed.

Assign the source column names to the table metadata:

subscriptions = graph["subscriptions"]
subscriptions.time_column = "valid_from"
subscriptions.end_time_column = "valid_to"

Assign None when an inferred column does not represent the intended table timeline.

The SDK’s general metadata inference can select a time column, but it does not infer an end-time column. Configure end_time_column explicitly when the source represents row validity.

Both designated columns must support the timestamp semantic type. Setting either property marks that column as timestamp, and the SDK rejects an incompatible physical data type. The primary key, time column, and end-time column must be different columns.

After making changes, inspect the metadata again and call graph.validate(). See Configure Table Metadata for the complete metadata workflow.

Entity-table validity at the anchor time

When predict() builds context examples from a Predictive Query Language (PQL) query, Kumo Relational applies the prediction entity table’s time and end-time columns. The prediction entity table contains the entities for which you want predictions, and these columns determine which of its rows are valid at the anchor time.

With both columns configured, the validity interval is half-open:

time_column <= anchor_time < end_time_column

A null end time means that the row remains valid with no known end.

Boundary condition	Entity row eligibility
`time_column` equals the anchor time	Included
`end_time_column` equals the anchor time	Excluded
`end_time_column` is later than the anchor time	Included
`end_time_column` is null	Included, subject to the start-time condition

If only time_column is configured, the row must start on or before the anchor time. If only end_time_column is configured, the row must end after the anchor time or have a null end time. If neither is configured, Kumo Relational does not apply a temporal eligibility filter to the entity table.

Behavior on other sampled tables

The full start/end validity interval does not apply to related rows sampled from every table in the graph.

For a sampled table that is not the prediction entity table:

time_column participates in temporal neighbor sampling so future rows are not sampled.
end_time_column does not remove a row whose validity ended before the anchor time.
An end-time value later than the corresponding anchor time is replaced with a missing timestamp in the context sent to the model. This prevents the future end time itself from becoming model input.

Do not treat end_time_column as a universal expired-row filter across the graph. Its complete start/end eligibility behavior applies to the prediction entity table. On other sampled tables, the current SDK does not use it to exclude rows that expired before the anchor time.

Relationship to prediction settings

Time and end-time columns are graph metadata. Configure them before calling client.relational(graph).predict(...); predict() does not have a request-level end_time argument.

The anchor_time prediction setting selects the reference time used for a request. See Time controls for request-level time settings.

Review checklist

The time column represents when a row became available, not merely when it was edited.
The end-time column represents the end of row validity.
Both source columns use compatible datetime values.
Open-ended rows use a null end time.
The same column is not assigned as a primary key, time column, and end-time column.
The graph metadata and relationships are validated after any correction.