> 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

Kumo Relational assigns each column both a physical data type and a semantic type.

* 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 public `kumo_relational_client.relational` facade exports `Dtype`, `Stype`, and `ViewConversionWarning`:

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

Kumo Relational infers physical and semantic types when you create a graph. Use these public enums when you need to inspect or correct inferred metadata, and use `ViewConversionWarning` to filter conversion diagnostics.

## Inspect and correct physical types

```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)
```

Correct physical data types in the source before creating the graph:

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

## Plan semantic meaning

Automatic inference is a starting point. Carefully review identifier-like integers, 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

| 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

Kumo Relational normalizes source-specific types into the following SDK data types. 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](/rfm/graph-creation). Then use [Configure Table Metadata](/rfm/table-definitions) to review inferred keys, timestamps, and semantic types.