Skip to navigation
Get Started

Quickstart: Kumo Relational

View as Markdown

Kumo Relational predicts outcomes from structured, multi-table data without requiring you to train a task-specific model first. In this quickstart, you use local pandas DataFrames to build a relational graph, which maps tables and their relationships, and send a prediction request to a Kumo Relational model deployed as an NVIDIA NIM inference service.

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 Linux x86-64 environment with CPython 3.10, 3.11, 3.12, or 3.13.
  • 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 first.

Standard SDK workflow

The SDK workflow has five steps:

  1. Prepare the related tables.
  2. Build and validate a relational graph with kumo_relational_client.relational.
  3. Describe the prediction task in Predictive Query Language (PQL), Kumo Relational’s SQL-like query language.
  4. Bind the graph with client.relational(graph).
  5. Call predict() with the query and prediction settings.

The result is a pandas DataFrame. Standard applications do not initialize the underlying Kumo Relational driver directly.

1. Install the SDK

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

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

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.

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:

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