Snowflake Connector

Use the Snowflake connector to create a Kumo Relational graph from tables in Snowflake. The graph represents your tables, column metadata, and relationships so Kumo Relational can sample the records relevant to a prediction without loading complete source tables into application memory. Kumo Relational sends the sampled context to the configured NVIDIA Inference Microservice (NIM), the service that runs predictions.

Installation

Install the SDK with the relational and Snowflake extras:

pip install "kumo-relational-client[relational,snowflake]"

Before creating a graph, ensure that your active Snowflake session or configured user can access the selected database and schema and read the source tables.

Quick Start

Choose the connection method that matches your environment.

Active Snowflake notebook session

In a Snowflake notebook, from_snowflake() automatically uses the active Snowpark session. Specify the database and schema that contain the tables for the graph:

from kumo_relational_client import relational
graph = relational.Graph.from_snowflake(
    database="MY_DATABASE",
    schema="MY_SCHEMA",
)

Explicit connection settings

Outside a Snowflake notebook, pass connection settings directly. Store credentials in a secret manager or environment variable instead of source files or notebooks:

import os
from kumo_relational_client import relational
graph = relational.Graph.from_snowflake(
    connection={
        "account": "my_account",
        "user": "my_user",
        "password": os.environ["SNOWFLAKE_PASSWORD"],
        "warehouse": "my_warehouse",
    },
    database="MY_DATABASE",
    schema="MY_SCHEMA",
)

Both methods perform the following actions:

1. Connects to the Snowflake database and schema.
2. Discovers all tables in the schema.
3. Infers column metadata, including physical data types, semantic roles, primary keys, and time columns.
4. Detects foreign-key relationships between tables.
5. Prints a summary of the inferred metadata and relationships.

Review the summary to confirm that the connector detected the intended keys, time columns, and relationships before using the graph for predictions.

Specifying Tables

By default, Kumo Relational includes every table it discovers in the schema. Use the tables parameter to include a subset of tables or override an inferred setting:

graph = relational.Graph.from_snowflake(
    tables=[
        "USERS",                                             # Include by name
        dict(name="ORDERS", source_name="ORDERS_SNAPSHOT"), # Map a source table
        dict(name="ITEMS", schema="OTHER_SCHEMA"),           # Use another schema
    ],
    database="DEFAULT_DB",
    schema="DEFAULT_SCHEMA",
)

Each entry can be a table name or a configuration dictionary with these keys:

Database and Schema Defaults

The database and schema parameters set defaults for all tables. If you omit these parameters, Kumo Relational uses the current database and schema from the active session.

Use the database and schema keys in a table configuration dictionary to override either default for that table.

Controlling Metadata Inference

By default, Graph.from_snowflake() infers metadata and relationships during graph creation. To run metadata and relationship inference later, set infer_metadata=False, then call the inference methods when you are ready:

graph = relational.Graph.from_snowflake(
    schema="MY_SCHEMA",
    infer_metadata=False,  # Skip automatic type inference
    verbose=False,         # Suppress output
)
# Run inference after creating the graph.
graph.infer_metadata()
graph.infer_links()

Manual Edge Specification

An edge represents a relationship from a foreign-key column in one table to the primary key of another table. Use the edges parameter to provide relationships explicitly when you do not want to rely on automatic detection. Each tuple contains the source table, its foreign-key column, and the referenced table:

graph = relational.Graph.from_snowflake(
    schema="MY_SCHEMA",
    edges=[
        ("ORDERS", "USER_ID", "USERS"),
        ("ORDERS", "ITEM_ID", "ITEMS"),
    ],
)

Pass edges=None to permit declared or inferred relationships. Pass edges=[] to create the graph without edges and suppress relationship inference.

Supported Snowflake Types

Each Snowflake physical type maps to a Kumo Relational data type (Dtype) and a default semantic type (Stype). The Dtype controls how values are represented, while the Stype tells Kumo Relational how to interpret them when sampling context.