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

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

Use the Kumo Relational Client to prepare a prediction request and send it to a
Kumo Relational NIM. In this quickstart, you build a relational graph from local
pandas DataFrames, bind it to `RelationalClient`, and receive predictions from
the deployed model. Model inference runs in the NIM.

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

## Before you begin

You need:

* A Python environment that meets the [client requirements](/kumo-relational/get-started/sdk-getting-started#client-requirements).
* The URL of a running Kumo Relational NIM that your environment can reach.
* An API key if a gateway in front of the NIM requires authentication.

If you do not have a reachable NIM endpoint, follow [Deploy, Install, and Connect](/kumo-relational/get-started/sdk-getting-started) first.

## 1. Install the SDK

```bash
pip install "kumo-relational-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 graph

Import the `relational` module, the SDK interface that constructs a Kumo Relational graph, and then infer the graph from the tables:

```python
from kumo_relational_client import relational

graph = relational.Graph.from_data({
    "users": users,
    "orders": orders,
})

graph.validate()
```

For production data, review the inferred table metadata and relationships before running predictions. Refer to [Build a Graph](/kumo-relational/user-guide/build-a-relational-graph/graph-creation).

## 4. Run a prediction

The sample query asks whether user `1` will place at least one order during the next 30 days.
Bind the graph to the client so the prediction can use the tables and their relationships, then send the query to your NIM endpoint:

> **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](/kumo-relational/get-started/sdk-getting-started#3-connect-to-the-nim).

```python
from kumo_relational_client import RelationalClient

query = "PREDICT COUNT(orders.*, 0, 30, days) > 0 FOR users.user_id=1"

with RelationalClient(url="http://localhost:8000") as client:
    result = client.relational(graph).predict(query, run_mode="fast")

print(result)
```

Replace `http://localhost:8000` with your NIM endpoint URL if it runs elsewhere.

A successful request returns a pandas DataFrame with an `ENTITY` column and, for this single-value prediction, a `PREDICTION` column.
A temporal request also includes `ANCHOR_TIMESTAMP`.
The prediction value depends on the deployed model and the supplied context.

Pass `api_key` to `RelationalClient` if a gateway in front of your deployment requires authentication.

## Next steps

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