Filters and Operators

Predictive Query Language (PQL), Kumo Relational’s SQL-like query language, controls which entities receive predictions and which historical records the model uses as context. An entity is the table key that identifies a record to score, such as a customer ID. Use the controls on this page to target specific entities, limit the history available to the model, reproduce a prediction at a past point in time, or evaluate a hypothetical attribute value.

• FOR and the indices parameter select the entities to score.
• WHERE filters historical context without changing which entities receive predictions.
• anchor_time and context_anchor_time set the reference times for prediction and context windows.
• ASSUMING conditions a prediction on a hypothetical attribute value without establishing that the value causes the outcome.

Select entities

Specify an explicit ID or list of IDs directly in the query:

PREDICT COUNT(orders.*, 0, 30, days) > 0
FOR customers.customer_id IN (42, 57, 81)

For a programmatically generated list, pass the IDs through the indices parameter of predict() instead of rewriting the query. The example assumes that graph contains a configured Kumo Relational graph.

from kumo_relational_client import RelationalClient
with RelationalClient(url="http://localhost:8000") as client:
    result = client.relational(graph).predict(
        "PREDICT COUNT(orders.*, 0, 30, days) > 0 "
        "FOR EACH customers.customer_id",
        indices=[42, 57, 81],
    )

The indices parameter overrides IDs embedded in the query. A single inference call accepts at most 1,000 IDs.

Filter historical context

Temporal WHERE filters restrict the prior events used as context without changing the entity list:

PREDICT COUNT(orders.*, 0, 30, days) > 0
FOR customers.customer_id=42
WHERE COUNT(orders.*, -30, 0, days) > 0

The WHERE clause retains historical context with at least one order during the 30 days before the anchor time.

Kumo Relational currently supports static column filters only when the filter stays within one table. The broader PQL grammar can describe joined static filters, but the Kumo Relational validator does not currently accept them.

PREDICT customers.segment
FOR customers.customer_id=42
WHERE customers.region = "North America"

Combine conditions

Use AND, OR, and NOT to combine type-compatible conditions:

PREDICT SUM(orders.amount, 0, 30, days) > 100
    OR COUNT(orders.*, 0, 30, days) > 10
FOR customers.customer_id=42
WHERE COUNT(orders.*, -90, 0, days) > 0

Start with one condition, and add other conditions only after the base query succeeds.

Set the anchor time

The anchor time defines “now” for temporal windows, including when a prediction horizon begins. Pass time controls directly to predict():

import pandas as pd
from kumo_relational_client import RelationalClient
with RelationalClient(url="http://localhost:8000") as client:
    result = client.relational(graph).predict(
        query,
        indices=[42, 57, 81],
        run_mode="fast",
        anchor_time=pd.Timestamp("2025-01-01T00:00:00Z"),
    )

An explicit historical anchor time lets you backtest predictions as if they were made at that point in time. Ensure that features and labels respect the time boundary so future information does not leak into the prediction.

Use "entity" when each row in the entity table has its own reference timestamp:

result = model.predict(query, anchor_time="entity")

Here, model is the graph-bound handle returned by client.relational(graph).

You can specify separate anchors for prediction and context. anchor_time sets the reference point for the prediction window, while context_anchor_time sets the reference point for the historical context:

result = model.predict(
    query,
    anchor_time=pd.Timestamp("2025-06-01T00:00:00Z"),
    context_anchor_time=pd.Timestamp("2025-03-01T00:00:00Z"),
)

Verify that the deployed SDK and NIM versions support the optional inference controls.

Condition with ASSUMING

Use ASSUMING to evaluate a prediction under a hypothetical attribute value:

PREDICT COUNT(orders.*, 0, 90, days) = 0
FOR customers.customer_id=42
ASSUMING customers.plan = "premium"

Kumo Relational conditions the prediction on in-context examples that have the specified value. This operation does not estimate a causal treatment effect, so the result is not proof that changing the attribute will cause the predicted outcome.

See the WHERE and ASSUMING sections for syntax details.