> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Snowflake Connector

> Connect Kumo Relational to data stored in Snowflake

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.
The client sends sampled context to the configured NIM endpoint for inference.

## Installation

Install the SDK with the relational and Snowflake extras:

```bash
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:

```python
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:

```python
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:

```python
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:

| Key           | Description                                                                                                              | Required |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ | -------- |
| `name`        | The graph table name used in Predictive Query Language (PQL), Kumo Relational's language for describing prediction tasks | Yes      |
| `source_name` | The Snowflake source table name when it differs from `name`                                                              | No       |
| `database`    | A database override for this table                                                                                       | No       |
| `schema`      | A schema override for this table                                                                                         | No       |
| `primary_key` | A primary-key override for this table                                                                                    | No       |

## 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:

```python
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

Use `edges` to provide relationships explicitly. Each tuple contains the
source table, its foreign-key column, and the referenced table. See
[Define Relationships](/kumo-relational/user-guide/build-a-relational-graph/graph-definitions)
for relationship semantics and corrections after graph creation:

```python
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.

| Snowflake type                                          | Kumo Relational `Dtype` | Default `Stype`         |
| ------------------------------------------------------- | ----------------------- | ----------------------- |
| `NUMBER`, `DECIMAL`, `INT`, `BIGINT`, `FLOAT`, `DOUBLE` | `float` or `int`        | `numerical`             |
| `VARCHAR`, `STRING`, `TEXT`, `CHAR`                     | `string`                | `categorical` or `text` |
| `BOOLEAN`                                               | `bool`                  | `categorical`           |
| `DATE`, `TIMESTAMP`, `TIMESTAMP_NTZ`, `TIMESTAMP_TZ`    | `date`                  | `timestamp`             |
| `ARRAY`                                                 | `stringlist`            | `multicategorical`      |
| `VECTOR`                                                | `floatlist`             | `sequence`              |