Matches Pattern Check FAQ

Answers to common questions about how the Matches Pattern check evaluates a regular expression, how anchoring and case behave, and how anomalies are reported, grouped by topic.

Behavior

Does the whole value have to match?

Only when the expression is anchored. ^...$ requires the entire value to match; without the anchors the pattern is found anywhere inside the value, so surrounding text still passes.

Is matching case-sensitive?

Yes. Build case-insensitivity into the expression (for example [A-Za-z]) or normalize the column upstream.

How are NULL values treated?

NULLs pass. An empty string does not: it is a present value that fails any pattern requiring at least one character. Pair with Not Null when absence should also be reported.

What happens on an array field?

Every element is tested and the row counts as failing as soon as one element does not match. Empty arrays and NULL arrays pass, since there is nothing to evaluate. An array check is evaluated column-level, so it reports a single Shape Anomaly rather than per-row Record Anomalies.

Does the filter run before or after the match?

Before. The platform applies the filter first and then evaluates only the rows that pass the filter. Filtered-out rows cannot trigger an anomaly and are not counted in the totals.

Anomaly Reporting

What do the anomaly messages look like?

Record Anomaly: <field> has the value <value>, which does not match the required format. Values should follow the pattern: <pattern>

Shape Anomaly: <field> values do not match the required format, affecting N of M asserted records. Values should follow the pattern: <pattern>

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 Matches Pattern produce Record Anomalies, Shape Anomalies, or both?

On a scalar text field: 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. On an array field the check always produces a Shape Anomaly, at any coverage.

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 Matches Pattern?

Yes. Matches Pattern 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 Matches Pattern 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 pattern on an existing check?

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

What permission do I need to create or edit a Matches Pattern 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.

When should I use Expected Values instead?

When the accepted values are a small, enumerable set. Expected Values states that rule directly and is easier to maintain than an expression listing the same options.