Filters and Operators

Filters and operators allow you to refine your predictions by controlling which data is used and which entities are included.

WHERE Clause (Context Filters)

The WHERE clause controls which historical rows are used as context examples for the prediction. These filters are not applied to the entity list itself — they only affect the context data that KumoRFM uses to generate features.

Temporal Filters

Filter context examples based on temporal aggregations. This is useful for focusing predictions on specific subsets of historical behavior.

1
-- Predict churn only for recently active users
2
-- (context limited to users who had an order in the last 30 days)
3
PREDICT COUNT(orders.*, 0, 30, days) > 0
4
FOR users.user_id=1
5
    WHERE COUNT(orders.*, -30, 0, days) > 0

1
query = """
2
PREDICT COUNT(orders.*, 0, 30, days) > 0
3
FOR users.user_id=1
4
    WHERE COUNT(orders.*, -30, 0, days) > 0
5
"""
6
result = model.predict(query)

The negative time offset (-30, 0) looks at the past 30 days relative to “now”, providing a temporal filter on the context.

Static Filters

Filter context examples based on static column values.

1
-- Predict spend on electronics category only
2
PREDICT SUM(transactions.value, 15, 45, days)
3
FOR EACH customers.customer_id
4
    WHERE transactions.category = "Electronics"

IN Clause (Entity Specification)

The IN clause specifies which entities to make predictions for. You can specify a single entity or a list of entities.

Single entity:

1
PREDICT COUNT(orders.*, 0, 30, days) > 0
2
FOR users.user_id=42

Multiple entities:

1
PREDICT COUNT(orders.*, 0, 30, days) > 0
2
FOR users.user_id IN (1, 2, 3)

Programmatic indices:

You can also pass entity IDs programmatically via the indices parameter:

1
result = model.predict(
2
    "PREDICT COUNT(orders.*, 0, 30, days) > 0 FOR users.user_id=1",
3
    indices=[1, 2, 3, 4, 5],
4
)

When indices is provided, it overrides the entity specification in the query string. For large entity lists, use KumoRFM.batch_mode().

Logical Operators

Combine multiple conditions using AND, OR, and NOT operators.

AND

Require all conditions to be true.

1
-- Predict spend in electronics with completed transactions only
2
PREDICT SUM(transactions.value, 15, 45, days)
3
FOR EACH customers.customer_id
4
    WHERE transactions.category = "Electronics"
5
        AND transactions.status = "completed"

OR

Require any one condition to be true. When used in the PREDICT clause, both operands must return the same type (e.g., both boolean for binary classification).

1
-- Predict high-value customer status:
2
-- (spend > $100 OR more than 10 transactions)
3
PREDICT SUM(transactions.value, 15, 45, days) > 100
4
        OR COUNT(transactions.*, 15, 45, days) > 10
5
FOR EACH customers.customer_id

NOT

Negate a condition.

1
-- Exclude customers in Alaska or California from context
2
PREDICT SUM(transactions.value, 15, 45, days) > 100
3
FOR EACH customers.customer_id
4
    WHERE customers.location NOT IN ("ALASKA", "CALIFORNIA")

Combined Example

1
-- Predict high-value customer status
2
-- For customers active in the last 40 days and not in Alaska/California
3
PREDICT SUM(transactions.value, 15, 45, days) > 100
4
        OR COUNT(transactions.*, 15, 45, days) > 10
5
FOR EACH customers.customer_id
6
    WHERE COUNT(transactions.*, -40, 0, days) > 0
7
        AND customers.location NOT IN ("ALASKA", "CALIFORNIA")

Anchor Time

The anchor time defines “now” — the reference point in time from which the prediction horizon is measured. By default, KumoRFM uses the maximum timestamp found in the data.

You can customize the anchor time via the anchor_time parameter in KumoRFM.predict() and KumoRFM.evaluate():

Default (auto-detect):

1
# Uses the maximum timestamp in the data as "now"
2
result = model.predict(query, anchor_time=None)

Explicit timestamp:

1
# Make predictions as if "now" were January 1, 2024
2
result = model.predict(
3
    query,
4
    anchor_time=pd.Timestamp("2024-01-01"),
5
)

This is useful for backtesting — evaluating what the model would have predicted at a past point in time using only data available then.

Per-entity timestamps:

Use anchor_time="entity" when each entity has its own meaningful reference point in time, rather than a single shared “now”. KumoRFM will use each entity’s own time column value as its anchor.

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

When to use this: Suppose you want to predict whether each user will churn in the 90 days following their sign-up date. User A signed up on January 1, user B on March 15 — you want the 90-day window to start from each user’s own sign-up date, not from a single shared date. With anchor_time="entity", KumoRFM uses the timestamp stored in the entity’s time column as “now” for that entity.

1
# Each user's 90-day churn window starts from their own sign-up date
2
query = "PREDICT COUNT(orders.*, 0, 90, days) = 0 FOR users.user_id IN (42, 123)"
3
result = model.predict(query, anchor_time="entity")

Context anchor time:

By default, KumoRFM uses the same anchor time for both the prediction and for collecting the historical context examples it learns from. You can decouple these using context_anchor_time.

1
result = model.predict(
2
    query,
3
    anchor_time=pd.Timestamp("2024-06-01"),
4
    context_anchor_time=pd.Timestamp("2024-03-01"),
5
)

When to use this: Suppose you want to generate predictions for June 2024, but you are running this job in March 2024 and only have data up to that point. Setting anchor_time to June 1 tells KumoRFM “predict from this future date”, while context_anchor_time set to March 1 tells it “build your context from data as it existed on March 1”. This is useful for forward-looking batch scoring where you want predictions for a future date using only data available today.

ASSUMING Clause

The ASSUMING clause lets you condition a prediction on a hypothetical state — asking “what would happen if this entity had a specific attribute value?”

1
-- Predict churn for user 42, assuming they are on the premium plan
2
PREDICT COUNT(orders.*, 0, 90, days) = 0
3
FOR users.user_id=42
4
ASSUMING users.plan = 'premium'

1
query = (
2
    "PREDICT COUNT(orders.*, 0, 90, days) = 0 "
3
    "FOR users.user_id=42 "
4
    "ASSUMING users.plan = 'premium'"
5
)
6
result = model.predict(query)

When to use this: Use ASSUMING to answer counterfactual questions — for example, “would this customer churn if we upgraded them to premium?” or “how would revenue change if this item were marked as featured?”

Unsupported Features

The following PQL features are not yet supported in KumoRFM:

• Only numerical and categorical columns are valid target columns.
• Filtering by column value is only supported for columns within the same table.