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

# Data Types and Semantic Types

> Understand physical data types and semantic column meaning in Kumo Relational

The client assigns each graph column a physical data type and a semantic type.
These determine storage conversion, validation, and how the column is used in
prediction context.

* The **data type** describes how values are stored, such as integers, floating-point numbers, strings, Boolean values, timestamps, or lists.
* The **semantic type** describes how Kumo Relational interprets those values, such as an ID, numerical feature, category, text field, timestamp, or sequence.

The client infers both types during graph construction.
Review the inferred types because identifiers, categories, and timestamps can look similar in source data but serve different purposes in a graph.

The public `kumo_relational_client.relational` module exports the `Dtype` and `Stype` enums for inspecting or correcting inferred metadata.
It also exports `ViewConversionWarning`, which you can use to filter warnings produced while source data is converted into a graph:

```python
from kumo_relational_client.relational import Dtype, Stype, ViewConversionWarning
```

## Inspect and correct physical types

Inspect source data types before creating the graph so that values are converted correctly.
For example, this DataFrame initially stores `signup_time` as strings:

```python
import pandas as pd

customers = pd.DataFrame({
    "customer_id": pd.Series([1, 2, 3], dtype="int64"),
    "segment": pd.Series(["small", "enterprise", "small"], dtype="string"),
    "notes": pd.Series(["prefers email", "", "new account"], dtype="string"),
    "signup_time": ["2024-01-01", "2024-02-15", "2024-03-20"],
})

print(customers.dtypes)
```

The output identifies the source dtype of each column and shows that `signup_time` is not yet a native datetime column.
Correct the physical data type in the source before creating the graph:

```python
customers["signup_time"] = pd.to_datetime(customers["signup_time"])
```

## Plan semantic meaning

Check inferred types for identifier columns, free-form strings, categories, and timestamps.
In the preceding example, `customer_id` must be an `ID`, `segment` must be `categorical`, `notes` must be `text`, and `signup_time` must be a `timestamp`.

Common semantic types include `ID`, `numerical`, `categorical`, `multicategorical`, `text`, `timestamp`, and `sequence`.
Each semantic type must be compatible with the column's physical data type; validation rejects incompatible metadata.

## Supported semantic types

Use this table when reviewing an inferred semantic type or choosing a compatible correction.

| Semantic type      | Use for                                                      | Compatible data types                                        |
| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `ID`               | Primary keys, foreign keys, and other entity identifiers     | Integer types, floating-point types, `string`, and `binary`  |
| `numerical`        | Quantities and continuous or discrete measurements           | Integer types, floating-point types, and `timedelta`         |
| `categorical`      | Boolean values or one label from a finite set                | `bool`, numerical types, `string`, `binary`, and `timedelta` |
| `multicategorical` | Zero or more labels associated with one row                  | `string`, `binary`, `intlist`, `floatlist`, and `stringlist` |
| `text`             | Free-form natural language whose content carries meaning     | `string`                                                     |
| `timestamp`        | Event times, entity reference times, and validity boundaries | `date`, `time`, or a timestamp-formatted `string`            |
| `sequence`         | Fixed-length numerical vectors or embeddings                 | `intlist`, `floatlist`, or `string`                          |

Use `ID` for every primary key and foreign key participating in a graph relationship.
Use `timestamp` for table time and end-time columns.
Although timestamp-formatted strings pass the compatibility check, convert them to a native datetime type before constructing the graph whenever possible.

## Supported physical data types

Use this table to understand how source-specific types are normalized into SDK data types and which semantic type Kumo Relational infers by default.
The exact source mapping depends on the source, such as pandas, SQLite, DuckDB, Snowflake, or Databricks.

| Data type                                | Typical source values                                          | Default inferred semantic type |
| ---------------------------------------- | -------------------------------------------------------------- | ------------------------------ |
| `bool`                                   | Boolean values                                                 | `categorical`                  |
| `int`, `byte`, `int16`, `int32`, `int64` | Integer values                                                 | `numerical`                    |
| `float`, `float32`, `float64`            | Floating-point values                                          | `numerical`                    |
| `string`                                 | Strings, pandas object columns, and pandas categorical columns | `text`                         |
| `binary`                                 | Binary strings or byte values                                  | `categorical`                  |
| `date`, `time`                           | Dates and timestamps                                           | `timestamp`                    |
| `timedelta`                              | Durations                                                      | `numerical`                    |
| `intlist`, `floatlist`                   | Homogeneous numerical lists                                    | `sequence`                     |
| `stringlist`                             | Homogeneous string lists                                       | `multicategorical`             |

Inference can select a more specific semantic type based on column names, uniqueness, cardinality, and values.
For example, an integer column can be inferred as `ID`, and a string column can be inferred as `categorical` or `timestamp`.

The physical data type is derived from the source.
To correct it, change the source column or pandas dtype before constructing the graph.
After constructing the graph, you can inspect the inferred metadata and correct semantic types, as long as the replacement is compatible with the column's physical data type.

Next, [create a graph](/kumo-relational/user-guide/build-a-relational-graph/graph-creation).
Then use [Configure Table Metadata](/kumo-relational/user-guide/build-a-relational-graph/table-definitions) to review inferred keys, timestamps, and semantic types.