> ## Documentation Index
> Fetch the complete documentation index at: https://kumo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# kumoai.graph

> Graph, Table, and Column — the relational schema definitions for Kumo

A Kumo `Graph` is a fundamental concept in the SDK. It links multiple `Table` objects (each created from a [`SourceTable`](/sdk/kumoai-connector#sourcetable)) into a relational schema that represents the relationships between tables for a specific business problem. Graphs are used as input to predictive queries and training jobs.

***

## Column

The metadata for a single column in a `Table` is represented by a `Column` object. Columns can be fetched from a table with [`Table.column()`](#column-1) and modified by adjusting their properties.

Related: [`Dtype`](/sdk/kumoai#dtype), [`Stype`](/sdk/kumoai#stype).

### `Column`

```python theme={null}
from kumoai.graph import Column

col = Column(name="order_date", stype="timestamp", dtype="date")
```

<ParamField body="name" type="str" required>
  The name of this column.
</ParamField>

<ParamField body="stype" type="Union[Stype, str]" default="None">
  The semantic type. Can be specified as a string — see [`Stype`](/sdk/kumoai#stype) for valid values.
</ParamField>

<ParamField body="dtype" type="Union[Dtype, str]" default="None">
  The data type. Can be specified as a string — see [`Dtype`](/sdk/kumoai#dtype) for valid values.
</ParamField>

<ParamField body="timestamp_format" type="Union[str, TimestampUnit]" default="None">
  For timestamp columns, the format string used to parse the value. Intelligently inferred by Kumo if not specified.
</ParamField>

***

## Table

A `Table` represents the full metadata for a table in a Kumo `Graph`. Unlike a `SourceTable` (which is just a reference to data behind a connector), a `Table` specifies selected columns, their data and semantic types, and relational constraint information (primary key, time column, end time column).

### `Table`

```python theme={null}
from kumoai.graph import Table

table = Table.from_source_table(
    source_table=src,
    primary_key="order_id",
    time_column="order_date",
)
```

<ParamField body="source_table" type="SourceTable" required>
  The source table this Kumo table is created from.
</ParamField>

<ParamField body="columns" type="Sequence[Union[SourceColumn, Column]]" default="None">
  The columns to include. Defaults to all columns from the source table. Each column must have its `dtype` and `stype` specified.
</ParamField>

<ParamField body="primary_key" type="Union[Column, str]" default="None">
  The primary key column, if present. Must exist in `columns`.
</ParamField>

<ParamField body="time_column" type="Union[Column, str]" default="None">
  The time column, if present. Must exist in `columns`.
</ParamField>

<ParamField body="end_time_column" type="Union[Column, str]" default="None">
  The end time column, if present. Must exist in `columns`.
</ParamField>

#### `from_source_table()` `staticmethod`

Convenience constructor that creates a `Table` from a `SourceTable`.

<ParamField body="source_table" type="SourceTable" required>
  The source table to create from.
</ParamField>

<ParamField body="column_names" type="List[str]" default="None">
  Column names to include. All columns are included if not specified.
</ParamField>

<ParamField body="primary_key" type="str" default="None">
  The primary key column name.
</ParamField>

<ParamField body="time_column" type="str" default="None">
  The time column name.
</ParamField>

<ParamField body="end_time_column" type="str" default="None">
  The end time column name.
</ParamField>

**Returns** `Table`

#### `columns` `property`

**Returns** `List[Column]` — All columns in this table.

#### `primary_key` `property`

**Returns** `Optional[Column]` — The primary key column, or `None`.

#### `time_column` `property`

**Returns** `Optional[Column]` — The time column, or `None`.

#### `end_time_column` `property`

**Returns** `Optional[Column]` — The end time column, or `None`.

#### `column()`

Returns the named column.

<ParamField body="name" type="str" required>
  The column name.
</ParamField>

**Returns** `Column`

#### `has_column()`

<ParamField body="name" type="str" required>
  The column name.
</ParamField>

**Returns** `bool` — `True` if the column exists in this table.

#### `add_column()`

Adds a `Column` to this table.

#### `remove_column()`

<ParamField body="name" type="str" required>
  The column name to remove.
</ParamField>

**Returns** `Table`

#### `infer_metadata()`

Infers any missing `dtype` and `stype` values from the source table.

<ParamField body="inplace" type="bool" default="True">
  Whether to modify the table in place or return a new `Table` object.
</ParamField>

**Returns** `Table`

#### `validate()`

Validates the table configuration for use with Kumo.

<ParamField body="verbose" type="bool" default="True">
  Whether to print validation output.
</ParamField>

**Returns** `Table`

#### `get_stats()`

Fetches column statistics from a snapshot of this table.

<ParamField body="wait_for" type="str" default="&#x22;minimal&#x22;">
  The snapshot wait level.
</ParamField>

**Returns** `Dict[str, Dict[str, Any]]`

#### `save()`

Saves the table to Kumo and returns its ID.

<ParamField body="name" type="str" default="None">
  Optional name to save the table under.
</ParamField>

**Returns** `str`

#### `load()` `classmethod`

Loads a previously saved table.

<ParamField body="table_id_or_template" type="str" required>
  The table ID or named template.
</ParamField>

**Returns** `Table`

#### `print_definition()`

Prints the full table definition with placeholder names.

***

## Graph

A `Graph` represents a full relational schema over a set of `Table` objects, including the primary key / foreign key relationships between them. Once a graph is created, you are ready to write a [`PredictiveQuery`](/sdk/kumoai-pquery#predictivequery) and train a model.

### `Graph`

```python theme={null}
from kumoai.graph import Graph

graph = Graph(
    tables={"users": users_table, "orders": orders_table},
    edges=[("orders", "user_id", "users")],
)
```

<ParamField body="tables" type="Dict[str, Table]" default="None">
  Tables in the graph, keyed by unique table name.
</ParamField>

<ParamField body="edges" type="Iterable[EdgeLike]" default="None">
  Foreign key relationships between tables. Each edge specifies `(src_table, fkey, dst_table)`.
</ParamField>

#### `id` `property`

**Returns** `str` — A unique identifier derived from the graph's schema. Two graphs with any difference in their tables or columns are guaranteed to have distinct IDs.

#### `snapshot_id` `property`

**Returns** `Optional[GraphSnapshotID]` — The snapshot ID, if available.

#### `tables` `property`

**Returns** `Dict[str, Table]`

#### `edges` `property`

**Returns** `List[Edge]`

#### `table()`

<ParamField body="name" type="str" required>
  The table name.
</ParamField>

**Returns** `Table`

#### `has_table()`

<ParamField body="name" type="str" required>
  The table name.
</ParamField>

**Returns** `bool`

#### `add_table()`

<ParamField body="name" type="str" required>
  The name to register the table under.
</ParamField>

<ParamField body="table" type="Table" required>
  The table to add.
</ParamField>

#### `remove_table()`

<ParamField body="name" type="str" required>
  The name of the table to remove.
</ParamField>

#### `link()`

Adds a foreign key edge to the graph.

<ParamField body="edge" type="Edge" required>
  The edge to add.
</ParamField>

#### `infer_metadata()`

Infers missing metadata in all tables in the graph.

<ParamField body="inplace" type="bool" default="True">
  Whether to modify the graph in place or return a new `Graph` object.
</ParamField>

**Returns** `Graph`

#### `infer_links()`

Automatically detects foreign key relationships between tables.

**Returns** `Graph`

#### `validate()`

Validates the graph structure before use with a predictive query.

<ParamField body="verbose" type="bool" default="True">
  Whether to print validation output.
</ParamField>

**Returns** `Graph`

#### `get_table_stats()`

Fetches statistics for all tables in the graph.

<ParamField body="wait_for" type="Optional[str]" default="None">
  The snapshot wait level.
</ParamField>

**Returns** `Dict[str, Dict[str, Any]]`

#### `get_edge_stats()`

<ParamField body="non_blocking" type="bool" default="False">
  If `True`, returns `None` immediately when edge statistics are not yet available. If `False`, blocks until statistics are ready.
</ParamField>

**Returns** `Optional[GraphHealthStats]` — Health statistics for each edge in the graph.

#### `visualize()`

Exports the graph structure as a Graphviz diagram.

<ParamField body="path" type="str" default="None">
  Output path for the diagram.
</ParamField>

<ParamField body="show_cols" type="bool" default="True">
  Whether to include column names in the diagram.
</ParamField>

#### `save()`

Saves the graph to Kumo.

<ParamField body="name" type="Optional[str]" default="None">
  Optional name for the saved graph.
</ParamField>

<ParamField body="skip_validation" type="bool" default="False">
  Whether to skip validation before saving.
</ParamField>

**Returns** `str`

#### `load()` `classmethod`

Loads a previously saved graph.

<ParamField body="graph_id_or_template" type="str" required>
  The graph ID or named template.
</ParamField>

**Returns** `Graph`

#### `print_definition()`

Prints the full graph definition with placeholder names.

***

### `Edge`

Represents a foreign key relationship between two tables. Edges are always bidirectional within Kumo.

```python theme={null}
from kumoai.graph import Edge

edge = Edge(src_table="orders", fkey="user_id", dst_table="users")
src_table, fkey, dst_table = edge  # supports unpacking
```

<ParamField body="src_table" type="str" required>
  The source table name. This table must have a foreign key column `fkey` that links to the destination table's primary key.
</ParamField>

<ParamField body="fkey" type="str" required>
  The name of the foreign key column in the source table.
</ParamField>

<ParamField body="dst_table" type="str" required>
  The destination table name. Must have a primary key that the source table's foreign key references.
</ParamField>

***

### `GraphHealthStats`

Contains edge-level health statistics computed as part of a `Graph` snapshot. Index with an `Edge` object to retrieve per-edge statistics.

```python theme={null}
stats = graph.get_edge_stats()
edge_stats = stats[Edge("orders", "user_id", "users")]
```