Predicted By Check FAQ¶

Answers to common questions about how the prediction is compared, how the tolerance behaves, and how anomalies are reported, grouped by topic.

Behavior¶

What exactly does the check compare?¶

The value your expression predicts for the row against the field's actual value on that same row. The row passes when the difference between them is at most the tolerance.

Does the tolerance apply in both directions?¶

Yes. The comparison uses the absolute difference, so the band extends equally above and below the prediction, and a difference exactly equal to the tolerance passes.

Is the tolerance a percentage?¶

No, it is an absolute number in the field's own units and does not scale with the prediction. For a relative comparison, use Satisfies Expression.

How are empty values treated?¶

They pass. When the expression returns NULL or the field is NULL, the row is not reported. Add a Not Null check on the field and on the columns the expression uses when a missing value should be flagged.

Can I use it on a date or timestamp field?¶

The form lists date and timestamp fields, but the expression can convert only the predicted side, so the field cannot be compared as a number. Use Satisfies Expression and convert both sides to the same unit, for example with unix_timestamp().

Anomaly Reporting¶

What do the anomaly messages look like?¶

Record Anomaly: <field> has the value <value>, which falls outside its predicted range. The prediction allows a tolerance of <tolerance> around the expression: <expression>

Shape Anomaly: <field> values fall outside their predicted range, affecting N of M asserted records. The prediction allows a tolerance of <tolerance> around the expression: <expression>

When a filter is set, the message names it at the end of its first sentence, as (applied to records where <expression>). Record and Shape Anomaly messages both carry it.

Does Predicted By produce Record Anomalies, Shape Anomalies, or both?¶

At 100% coverage (the default), violating rows are reported as Record Anomalies. Below 100% coverage, a failed coverage assertion produces one Shape Anomaly for the dataset.

Scan settings can group a large number of Record Anomalies into one rolled-up Shape Anomaly, which carries the Shape Anomaly message. This behavior applies across rule types and is documented under Maximum Record Anomalies per Check.

Does Custom Anomaly Description work for Predicted By?¶

Yes. Predicted By emits Record Anomalies, so the anomaly_message_field payload field (and the Custom Anomaly Description toggle in the UI) applies.

When the option points at another column on the same row, the Record Anomaly message becomes that column's value for the violating row, shown as written. When the column is null, missing, or empty, the message falls back to the rule's standard wording, and when the column is masked the message reads <masked>. Shape Anomaly messages are unaffected.

Configuration¶

Can I lower the coverage on a Predicted By check?¶

Yes. Coverage at 1.0 (100%) means every row must pass. Lowering coverage to 0.995 allows up to 0.5% of rows to fail without raising an anomaly; once the failing fraction goes past that, the check reports a Shape Anomaly. Use lower coverage with care: a real regression that happens to fall just under the threshold will not raise an alert at all.

Can I change the expression or the tolerance later?¶

Yes. In the UI, open the check, edit either property, and click Update; see Edit a Check for the full steps. Through the API, a PUT to /api/quality-checks/{id} updates the properties object. The rule type, the target container, and the associated Check Template stay immutable.

What permission do I need to create or edit a Predicted By check?¶

The Drafter team permission on the datastore covers Draft work (creating a check as Draft or editing it while it stays Draft). Anything that puts the check into evaluation, such as creating or editing an Active check, archiving, or deleting, requires the Author team permission (or above). Viewing only requires Reporter. See Permissions for the full matrix.

Should I use Predicted By or a simpler rule?¶

Use Predicted By when the expected value has to be computed per row. When the reference is simply another column, Equal To Field says so more clearly; when it is a constant, Equal To does.