Prediction Types

Kumo Relational uses connected tables to predict numeric values, classes, ranked items, and time series. Use this reference to choose between temporal tasks, which predict outcomes over a future time horizon, and static tasks, which infer current or unknown attributes without a time component.

Each example shows a query in Predictive Query Language (PQL), Kumo Relational’s SQL-like language for describing what to predict and which entity to predict it for. The Python snippets run those queries with the NVIDIA Kumo Relational Client. They assume that graph has already been defined:

from kumo_relational_client import RelationalClient
def predict(query):
    with RelationalClient(url="http://localhost:8000") as client:
        return client.relational(graph).predict(query, run_mode="fast")

Temporal Tasks (Forecast)

Temporal tasks use historical data from related tables to predict future outcomes over a defined time horizon. Every temporal prediction has three components:

• Target: What to predict, expressed as an aggregation such as SUM or COUNT
• Entity: The row to predict for, identified by a table primary key
• Horizon: The future time window covered by the prediction

The general PQL pattern for temporal tasks is:

PREDICT <aggregation>(table.column, <start>, <end>, <unit>) FOR entity_table.pk=value

In this pattern, <start> and <end> define the future time window relative to “now.” The <unit> value specifies the time granularity, such as days, hours, or minutes.

Forecast: Regression

Predict a continuous numeric value for an entity over a future time horizon.

Use cases: Demand forecasting, revenue prediction, and quantity estimation.

Supported aggregations: SUM, AVG, COUNT, MAX, MIN

-- Predict total revenue for item_id=42 in the next 30 days
PREDICT SUM(orders.price, 0, 30, days)
FOR items.item_id=42

result = predict(
    "PREDICT SUM(orders.price, 0, 30, days) FOR items.item_id=42"
)

Output: A numeric value for each entity. For quantile output, see Configuration.

Metrics: mae, mse, rmse, mape, smape, and r2.

Forecast: Binary Classification

Predict whether an entity will or will not experience an event within a future time window. A boolean condition applied to an aggregation expression defines the two possible outcomes.

Use cases: Customer churn prediction and event occurrence prediction.

Supported aggregations: SUM, AVG, COUNT, MAX, MIN (with a boolean condition such as = 0, > 100)

-- Predict whether user_id=42 will make zero orders in the next 90 days (churn)
PREDICT COUNT(orders.*, 0, 90, days) = 0
FOR users.user_id=42

result = predict(
    "PREDICT COUNT(orders.*, 0, 90, days) = 0 FOR users.user_id=42"
)

The boolean condition (= 0, > 100, etc.) on the aggregation makes this a binary classification task.

Output: A Boolean value (True or False) and a probability for each entity.

Metrics: acc, auroc, auprc, ap, precision, recall, and f1.

Forecast: Multi-Class Classification

Predict which class or state an entity will belong to at a future point in time. Use FIRST() to predict the first value that occurs in the window, or LAST() to predict the final value.

Use cases: Tier migration, lifecycle stage prediction, and feature engagement.

Supported aggregations: FIRST, LAST

-- Predict what subscription tier user_id=42 will be in after 30 days
PREDICT FIRST(subscriptions.tier, 0, 30, days)
FOR users.user_id=42

result = predict(
    "PREDICT FIRST(subscriptions.tier, 0, 30, days) FOR users.user_id=42"
)

Output: One row for each entity and class, with CLASS, SCORE, and PREDICTED fields. PREDICTED=True marks the winning class.

Metrics: acc, precision, recall, f1, and mrr.

Recommendations

Predict a ranked list of items an entity is most likely to interact with over a future time window. Use LIST_DISTINCT() with RANK TOP N to return the top N recommended items.

Use cases: Product recommendations, content ranking, and next best action.

Supported aggregations: LIST_DISTINCT with RANK TOP N

-- Predict the top 10 items user_id=42 is most likely to order in the next 30 days
PREDICT LIST_DISTINCT(orders.item_id, 0, 30, days) RANK TOP 10
FOR users.user_id=42

result = predict(
    "PREDICT LIST_DISTINCT(orders.item_id, 0, 30, days) RANK TOP 10 "
    "FOR users.user_id=42"
)

Output: A ranked list of item IDs for each entity.

Metrics: map@k, ndcg@k, mrr@k, precision@k, recall@k, f1@k, hit_ratio@k.

Multi-Horizon Regression (Forecasting)

Predict a numeric value for an entity across multiple future time steps. This task produces a time series of predictions.

Use cases: Multi-step demand forecasting and time series prediction.

Supported aggregations: SUM, COUNT, COUNT_DISTINCT

-- Predict weekly revenue for item_id=42 over the next 60 weeks
PREDICT SUM(orders.price, 0, 7, days) FORECAST 60 TIMEFRAMES
FOR items.item_id=42

result = predict(
    "PREDICT SUM(orders.price, 0, 7, days) FORECAST 60 TIMEFRAMES "
    "FOR items.item_id=42"
)

The FORECAST N TIMEFRAMES clause tells Kumo Relational to produce N predictions, each separated by the time window specified in the aggregation, which is 7 days in this example. Therefore, FORECAST 60 TIMEFRAMES with a 7-day window covers 60 × 7 = 420 days.

Output: Time-indexed numeric values, one for each horizon. For quantile output, refer to Configuration.

Metrics: mae, mse, rmse, mape, smape, and r2.

Static Tasks

Static tasks infer current or unknown entity attributes from an entity’s attributes and relationships. A static prediction has no future time horizon.

Every static prediction has two components: the target attribute to infer and the entity to predict it for.

The general PQL pattern for static tasks is:

PREDICT table.column FOR entity_table.pk=value

Static Regression

Infer a continuous numeric attribute of an entity.

Use cases: Age estimation, price imputation, and value scoring.

Supported target type: Numeric columns

-- Predict the age of user_id=42
PREDICT users.age
FOR users.user_id=42

result = predict("PREDICT users.age FOR users.user_id=42")

Output: A numeric value for each entity. For quantile output, see Configuration.

Metrics: mae, mse, rmse, mape, smape, and r2.

Static Binary Classification

Infer whether an entity belongs to one of two classes based on its attributes.

Use cases: Fraud detection and quality classification.

Supported target type: Boolean columns

-- Predict whether transaction_id=42 is fraudulent
PREDICT transactions.is_fraudulent
FOR transactions.transaction_id=42

result = predict(
    "PREDICT transactions.is_fraudulent FOR transactions.transaction_id=42"
)

Output: A Boolean value (True or False) and a probability for each entity.

Metrics: acc, auroc, auprc, ap, precision, recall, and f1.

Static Multi-Class Classification

Infer which single class an entity belongs to from a set of possible classes.

Use cases: Customer segmentation and category prediction.

Supported target type: Categorical columns

-- Predict the customer segment for customer_id=42
PREDICT customers.segment
FOR customers.customer_id=42

result = predict(
    "PREDICT customers.segment FOR customers.customer_id=42"
)

Output: One row for each entity and class, with CLASS, SCORE, and PREDICTED fields. PREDICTED=True marks the winning class.

Metrics: acc, precision, recall, f1, and mrr.

Summary

Use this table to match the outcome you need with its PQL pattern and output type.