Skip to navigation
ReferenceAPI

kumoai.graph

View as Markdown

A Kumo Graph is a core SDK concept. It links multiple Table objects (each created from a 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

A Column object holds the metadata for a single column in a Table. Use Table.column() to fetch a column and adjust its properties.

Related: Dtype, Stype.

Column

from kumoai.graph import Column
col = Column(name="order_date", stype="timestamp", dtype="date")
name
strRequired

The name of this column.

stype
Union[Stype, str]Defaults to None

The semantic type. Can be specified as a string. Refer to Stype for valid values.

dtype
Union[Dtype, str]Defaults to None

The data type. Can be specified as a string. Refer to Dtype for valid values.

timestamp_format
Union[str, TimestampUnit]Defaults to None

For timestamp columns, the format string used to parse the value. Inferred by Kumo if not specified.

Table

A Table represents the full metadata for a table in a Kumo Graph. Unlike a SourceTable (which is 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

from kumoai.graph import Table
table = Table.from_source_table(
    source_table=src,
    primary_key="order_id",
    time_column="order_date",
)
source_table
SourceTableRequired

The source table this Kumo table is created from.

columns
Sequence[Union[SourceColumn, Column]]Defaults to None

The columns to include. Defaults to all columns from the source table. Each column must have its dtype and stype specified.

primary_key
Union[Column, str]Defaults to None

The primary key column, if present. Must exist in columns.

time_column
Union[Column, str]Defaults to None

The time column, if present. Must exist in columns.

end_time_column
Union[Column, str]Defaults to None

The end time column, if present. Must exist in columns.

from_source_table() staticmethod

Creates a Table from a SourceTable.

source_table
SourceTableRequired

The source table to create from.

column_names
List[str]Defaults to None

Column names to include. All columns are included if not specified.

primary_key
strDefaults to None

The primary key column name.

time_column
strDefaults to None

The time column name.

end_time_column
strDefaults to None

The end time column name.

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.

name
strRequired

The column name.

Returns Column

has_column()

Checks whether the named column exists in this table.

name
strRequired

The column name.

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

add_column()

Adds a Column to this table.

remove_column()

name
strRequired

The column name to remove.

Returns Table

infer_metadata()

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

inplace
boolDefaults to True

Whether to modify the table in place or return a new Table object.

Returns Table

validate()

Validates the table configuration for use with Kumo.

verbose
boolDefaults to True

Whether to print validation output.

Returns Table

get_stats()

Fetches column statistics from a snapshot of this table.

wait_for
strDefaults to "minimal"

The snapshot wait level.

Returns Dict[str, Dict[str, Any]]

save()

Saves the table to Kumo and returns its ID.

name
strDefaults to None

Optional name to save the table under.

Returns str

load() classmethod

Loads a previously saved table.

table_id_or_template
strRequired

The table ID or named template.

Returns Table

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. After a graph is created, you are ready to write a PredictiveQuery and train a model.

Graph

from kumoai.graph import Graph
graph = Graph(
    tables={"users": users_table, "orders": orders_table},
    edges=[("orders", "user_id", "users")],
)
tables
Dict[str, Table]Defaults to None

Tables in the graph, keyed by unique table name.

edges
Iterable[EdgeLike]Defaults to None

Foreign key relationships between tables. Each edge specifies (src_table, fkey, dst_table).

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

name
strRequired

The table name.

Returns Table

has_table()

name
strRequired

The table name.

Returns bool

add_table()

name
strRequired

The name to register the table under.

table
TableRequired

The table to add.

remove_table()

name
strRequired

The name of the table to remove.

Adds a foreign key edge to the graph.

edge
EdgeRequired

The edge to add.

infer_metadata()

Infers missing metadata in all tables in the graph.

inplace
boolDefaults to True

Whether to modify the graph in place or return a new Graph object.

Returns Graph

Automatically detects foreign key relationships between tables.

Returns Graph

validate()

Validates the graph structure before use with a predictive query.

verbose
boolDefaults to True

Whether to print validation output.

Returns Graph

get_table_stats()

Fetches statistics for all tables in the graph.

wait_for
Optional[str]Defaults to None

The snapshot wait level.

Returns Dict[str, Dict[str, Any]]

get_edge_stats()

Fetches health statistics for all edges in the graph.

non_blocking
boolDefaults to False

If True, returns None immediately when edge statistics are not yet available. If False, blocks until statistics are ready.

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

visualize()

Exports the graph structure as a Graphviz diagram.

path
strDefaults to None

Output path for the diagram.

show_cols
boolDefaults to True

Whether to include column names in the diagram.

save()

Saves the graph to Kumo.

name
Optional[str]Defaults to None

Optional name for the saved graph.

skip_validation
boolDefaults to False

Whether to skip validation before saving.

Returns str

load() classmethod

Loads a previously saved graph.

graph_id_or_template
strRequired

The graph ID or named template.

Returns Graph

Prints the full graph definition with placeholder names.

Edge

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

from kumoai.graph import Edge
edge = Edge(src_table="orders", fkey="user_id", dst_table="users")
src_table, fkey, dst_table = edge  # supports unpacking
src_table
strRequired

The source table name. This table must have a foreign key column fkey that links to the destination table’s primary key.

fkey
strRequired

The name of the foreign key column in the source table.

dst_table
strRequired

The destination table name. Must have a primary key that the source table’s foreign key references.

GraphHealthStats

Holds edge-level health statistics from a Graph snapshot. Use an Edge as the index key to retrieve per-edge statistics.

stats = graph.get_edge_stats()
edge_stats = stats[Edge("orders", "user_id", "users")]