> This page is for Structured Data Models Client.

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

> Choose a table's time column 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 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`.

> **Warning**
>
> `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:

```python
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:

```python
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](/sdgm/kumo-relational/user-guide/build-a-relational-graph/table-definitions) 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](/sdgm/kumo-relational/user-guide/make-predictions/filters-and-operators#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.