Skip to navigation
Kumo RelationalGet Started

Quickstart: Kumo Relational

View as Markdown

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

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

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

2. Prepare relational data

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

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

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.

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