Data Types and Semantic Types

Kumo Relational classifies every column in two ways before it builds a graph from your tables. These classifications determine how Kumo Relational validates and interprets each column, including whether the column represents an identifier, category, timestamp, or feature.

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

Kumo Relational infers both types when you create a graph, which represents your tables and their relationships. 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:

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:

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:

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

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

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.

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. Then use Configure Table Metadata to review inferred keys, timestamps, and semantic types.