Time and End-Time Columns

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

• 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

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

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

Assign the source column name to the table metadata, for example, graph["subscriptions"].time_column = "valid_from" and graph["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; 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() derives context examples from PQL, Kumo Relational uses the prediction entity table’s time and end-time columns to determine which entity rows are valid at an 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.

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 is not applied to every table in the sampled relational neighborhood.

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 materialized context. This prevents the future end time itself from becoming model input.

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.