> 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

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:

```python
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](/kumo-relational/user-guide/build-a-relational-graph/table-definitions) 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.

> **Warning**
>
> 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](/kumo-relational/user-guide/configure-and-scale/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.