Create a Graph

A Kumo Relational graph describes your tables and how their rows connect. Kumo uses this structure to find related data that can provide context for a prediction. Create the graph after preparing the source data and assigning each column its physical data type, which describes how the source stores its values.

Choose a graph backend

Choose the entry point that matches where your data is stored. Use Graph.from_data() for DataFrames already loaded into your application, or use a source-specific factory to connect directly to a database or warehouse.

Local DataFrames must fit in application memory. This requirement includes DataFrames loaded from Amazon S3 with read("s3"). Database- and warehouse-backed graphs query and sample data from their respective sources; refer to the connector pages for information about permissions and connection behavior.

Factories that accept local file paths do not fetch remote URLs and reject paths that use URI schemes. They also reject unsupported file extensions and unrecognized connector keyword arguments.

Create a graph from DataFrames

The following example uses the prepared customers, orders, and products DataFrames from Data Requirements:

from kumo_relational_client import relational
graph = relational.Graph.from_data({
    "customers": customers,
    "orders": orders,
    "products": products,
})

Graph.from_data() creates the graph and infers table metadata and relationships. Table metadata describes the columns and their roles, while relationships identify how rows in different tables connect. Treat the inferred values as a starting point; the following pages explain how to inspect and correct them.

For every Graph.from_*() factory, an edge represents a relationship between two tables. The default, edges=None, permits declared or inferred relationships. Pass edges=[] only when you want a graph with no relationships and want to suppress relationship inference.

Create a connector-backed graph

For data stored in a database or warehouse, use the corresponding factory and connector configuration. The connector pages provide the required permissions, connection parameters, and examples:

• SQLite
• DuckDB
• Snowflake
• Databricks
• Amazon S3

Database- and warehouse-backed graphs retain table definitions that reference the source and query it when Kumo Relational needs related data for a prediction. S3 reads instead materialize each object into a DataFrame before graph creation.

Handle specialized sources and connection changes

Some graph factories require additional setup or checks.

RelBench: Install the relbench extra before using Graph.from_relbench().

Databricks metric views and Snowflake semantic views: These constructors convert source view metadata into graph tables and relationships. Review graph.conversion_messages after conversion. If your application handles those diagnostics separately, filter the corresponding warnings explicitly:

import warnings
from kumo_relational_client.relational import ViewConversionWarning
warnings.filterwarnings("ignore", category=ViewConversionWarning)

Updated credentials or warehouse sessions: Call graph.update_connection(...) to reconnect a source-backed graph without rebuilding its metadata.

Next, configure the inferred table metadata.