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

# Time and End-Time Columns

> Choose table time and end-time metadata and understand how Kumo Relational uses it during sampling

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

| 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

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](/rfm/table-definitions) 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.

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

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](/rfm/configuration#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.