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

# Filters and Operators

> Use entity selection, context filters, anchor times, and assumptions in Kumo Relational

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:

```sql
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.

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

```sql
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.

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

```sql
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()`:

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

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

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

```sql
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.

> **Warning**
>
> Use an assumed state only when it has adequate historical representation. Check the stability of the results across related cohorts, protect sensitive attributes, and do not use an assumed association as the sole basis for a high-stakes decision.

See the [`WHERE`](#where) and [`ASSUMING`](#assuming) sections for syntax details.