> This page is for Structured Data Models Client.

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

# Quickstart: Kumo Relational

> Build a relational schema and run your first prediction against a Kumo Relational NIM

This quickstart uses local pandas DataFrames to build a relational schema and run a Kumo Relational prediction through an NVIDIA NIM.

> **Note**
>
> The small tables are for API verification only. They do not contain enough historical examples to assess prediction quality.

## Standard SDK workflow

After you install the SDK and make the Kumo Relational NIM available, use the following workflow:

1. Prepare the related tables.
2. Build a `Schema` with `sdm_client.Schema.from_data()` and review the inferred metadata and relationships.
3. Write the prediction task in PQL.
4. Materialize a `Request` with `PredictiveQuery(...).materialize(indices=...)`.
5. Call `predict()` with the request and the `KumoRelational` model.

The result is a `PredictionResult`; `to_pandas()` gives you a DataFrame.

## 1. Install the SDK

```bash
pip install "structured-data-models-client[relational]"
```

## 2. Prepare relational data

```python
import pandas as pd

users = pd.DataFrame({
    "user_id": [1, 2, 3],
    "signup_date": pd.to_datetime(["2024-01-01", "2024-02-15", "2024-03-20"]),
})

orders = pd.DataFrame({
    "order_id": [101, 102, 103, 104],
    "user_id": [1, 1, 2, 3],
    "price": [50.0, 30.0, 100.0, 75.0],
    "timestamp": pd.to_datetime([
        "2025-01-10", "2025-02-15", "2025-01-20", "2025-03-05"
    ]),
})
```

## 3. Build a schema

```python
from sdm_client import Schema

schema = Schema.from_data({
    "users": users,
    "orders": orders,
})
```

`Schema.from_data()` infers table metadata and relationships from the DataFrames you give it. Treat this inference as a starting point; the following pages explain how to inspect and correct it. For tables too large to load into memory, [`Schema.from_source`](/sdgm/kumo-relational/user-guide/build-a-relational-graph/graph-creation#schemas-over-tables-that-stay-in-place) samples a warehouse or database directly.

## 4. Run a prediction

Write the question in PQL, materialize it against the entities you want scored, and predict:

> **Note**
>
> This standalone example uses a context manager to create and close the client. For an application or notebook that makes multiple requests, follow the [reusable client pattern](/sdgm/kumo-relational/get-started/sdk-getting-started#3-connect-to-the-nim).

```python
from sdm_client import PredictiveQuery, SDMClient, KumoRelational

query = PredictiveQuery(
    "PREDICT COUNT(orders.*, 0, 30, days) > 0 FOR EACH users.user_id",
    schema,
)
request = query.materialize(indices=[1])

with SDMClient(url="http://localhost:8000") as client:
    result = client.predict(request, model=KumoRelational())

print(result.to_pandas())
```

The returned DataFrame includes `row_index` and, for this scalar task, `prediction` and `probability_<class>` columns. The prediction value depends on the deployed model and the supplied context.

Pass `api_key` to `SDMClient` if your deployment has an authenticating gateway.

## Next steps

* [Learn the data requirements](/sdgm/kumo-relational/user-guide/prepare-data/data-requirements)
* [Write predictive queries](/sdgm/kumo-relational/user-guide/make-predictions/writing-predictive-queries)
* [Explore prediction types](/sdgm/kumo-relational/user-guide/make-predictions/prediction-types)
* [Understand prediction results](/sdgm/kumo-relational/user-guide/work-with-prediction-results/prediction-results)
* [Open examples and notebooks](/sdgm/kumo-relational/user-guide/examples-and-notebooks/notebooks)