How Predicted By Checks Work

Definition

Asserts that the actual value of a field falls within an expected predicted range.

Overview

The Predicted By rule evaluates a prediction expression for each row and compares the result against the field's actual value. The row passes when the two are within the configured Tolerance of each other, in either direction.

In other words, the check tests |predicted - actual| <= tolerance. The expression supplies the prediction, the tolerance supplies the band around it, and the rule reports the rows that fall outside.

What makes it different from a fixed comparison is that the expected value is computed per row. A column that should track another column, follow a formula, or stay close to a derived figure has no single correct value, only a correct relationship, and this rule states that relationship directly.

Typical use cases:

• Confirm a derived column still matches the formula that produced it.
• Validate a forecast against what actually happened, within an accepted margin.
• Monitor a metric that should track another one closely.

Field Scope

Single: The rule evaluates one field per check. It accepts Integral, Fractional, Date, and Timestamp fields.

Accepted Types

General Properties

The filter allows you to define a subset of data upon which the rule will operate.

It requires a valid Spark SQL expression that determines the criteria rows in the DataFrame should meet. This means the expression specifies which rows the DataFrame should include based on those criteria. Since it's applied directly to the Spark DataFrame, traditional SQL constructs like WHERE clauses are not supported.

O_TOTALPRICE > 1000

C_MKTSEGMENT = 'BUILDING'

WHERE O_TOTALPRICE > 1000

WHERE C_MKTSEGMENT = 'BUILDING'

O_ORDERPRIORITY = '1-URGENT' AND O_ORDERSTATUS = 'O'

(L_SHIPDATE = '1998-09-02' OR L_RECEIPTDATE = '1998-09-01') AND L_RETURNFLAG = 'R'

WHERE O_ORDERPRIORITY = '1-URGENT' AND O_ORDERSTATUS = 'O'

O_TOTALPRICE > 1000, O_ORDERSTATUS = 'O'

RIGHT(
    O_ORDERPRIORITY,
    LENGTH(O_ORDERPRIORITY) - INSTR('-', O_ORDERPRIORITY)
) = 'URGENT'

LEVENSHTEIN(C_NAME, 'Supplier#000000001') < 7

RIGHT(
    O_ORDERPRIORITY,
    LENGTH(O_ORDERPRIORITY) - CHARINDEX('-', O_ORDERPRIORITY)
) = 'URGENT'

EDITDISTANCE(C_NAME, 'Supplier#000000001') < 7

O_ORDERSTATUS IN (
    SELECT DISTINCT O_ORDERSTATUS
    FROM {{_qualytics_self}}
    WHERE O_TOTALPRICE > 1000
)

O_ORDERSTATUS IN (
    SELECT DISTINCT O_ORDERSTATUS
    FROM ORDERS
    WHERE O_TOTALPRICE > 1000
)

Specific Properties

Predicted By has the following rule-specific properties:

Anomaly Types

Evaluation Flow

Every Predicted By check follows the same five-step evaluation flow:

1. Apply the filter clause. If the check has a filter set, only rows matching the filter expression continue to the next step. Rows outside the filter are ignored and cannot contribute to the violation count.
2. Resolve any check variables. Placeholders in the expression are replaced with their values before it runs.
3. Evaluate the prediction. The expression runs against the current row, producing the value the field is expected to hold.
4. Compare it against the actual value. The row passes when the difference between the prediction and the field's value is at most Tolerance, in either direction. The band is inclusive: a difference exactly equal to the tolerance passes.
5. Apply coverage. At 100% coverage, any failing row causes the check to fail. Below 100% coverage, the check fails only when the passing fraction drops below the threshold (see Coverage and Tolerance).

The Tolerance Is a Band, Not a Direction

The comparison uses the absolute difference, so the tolerance applies equally above and below the prediction. A tolerance of 2 accepts anything from predicted - 2 to predicted + 2.

The rule cannot express a one-sided allowance such as "the actual value may exceed the prediction but never fall short". For that, compare the two sides with Satisfies Expression, which lets you write the inequality you actually want.

The Tolerance Is Absolute, Not a Percentage

Tolerance is a fixed number in the field's own units. It does not scale with the size of the prediction, so a tolerance sized for values around 100 will be far too tight on values around 100,000 and far too loose the other way.

When a column spans several orders of magnitude, either scope the check to a comparable slice with a filter, or express the relative comparison yourself in a Satisfies Expression check.

A Prediction That Returns Nothing Fails the Row

The row passes only when the difference is definitely within the tolerance. If the expression returns nothing, because a column it references is empty, the comparison produces no verdict and the row is reported.

That means Predicted By does not quietly pass empty values the way most field rules do. When a missing input should be tolerated, exclude those rows with a Filter Clause so they never reach the comparison.

Date and Timestamp Targets Have a Limitation

Although Date and Timestamp fields are available in the form, the Expression can transform only the predicted value. The selected field remains a date or timestamp, so converting the prediction to Unix time does not create a valid numeric comparison.

When both sides must be normalized to seconds, milliseconds, or another numeric unit, use Satisfies Expression to write the complete comparison explicitly.

The Expression Runs on Every Row

The prediction is computed once per row that passes the filter, so a heavy expression, especially one containing a subquery, makes the check considerably slower than a plain field comparison.

Narrow the rows with a Filter Clause before reaching for a more complicated expression: the filter runs first, so scoping the rows scopes the work.

The Filter Clause

The filter clause is a SQL WHERE expression applied before the evaluation. Filtered-out rows are ignored entirely (they cannot trigger a violation and are not counted in the totals).

When a filter is set, both the Record Anomaly and the Shape Anomaly messages end with [filter: <expression>] so the evaluated scope is visible in the alert.

Coverage and Tolerance

Coverage is a fractional value between 0 and 1 that defines the minimum fraction of evaluated rows that must pass:

• 1.0 (100%, default): every row in the filtered set must pass. Any failing row causes the check to fail. This is the strictest setting.
• < 1.0: the check tolerates a fraction of rows failing. The check fails only when the fraction of passing rows drops below the threshold.

Lower coverage values are useful when a small, known fraction of failures is expected. Use coverage carefully: a 0.5% tolerance can mask a real regression that happens to fall just under the threshold.

See Also