# Matches Pattern Check Examples

Source: https://userguide.qualytics.io/data-quality-checks/matches-pattern/deep-dive/examples/

Three real-world scenarios that show how the Matches Pattern check is typically used in production: enforcing an order reference format, validating postal codes for one country with a filter, and auditing a legacy identifier column mid-cleanup. The first two run at 100% coverage and report Record Anomalies; the third lowers coverage and reports a Shape Anomaly instead.

**Tab: Order Reference Format**

**The situation:** Every order carries a reference shaped `ORD-` followed by four digits. Rows that hold a bare number, a legacy prefix, or free text break the integration that parses the reference downstream. The whole value must match, so the expression is anchored.

**Check configuration**

| Field | Value |
| --- | --- |
| Rule | Matches Pattern |
| Field | `order_ref` |
| Filter | *(none)* |
| Custom Anomaly Description | Off |
| Pattern | `^ORD-[0-9]{4}$` |
| Coverage | 100% |
| Owner | *(check creator)* |
| Anomaly Assignee | *(Order Management)* |
| Description | Order reference must follow the ORD-0000 format. |
| Tags | `orders`, `format` |
| Additional Metadata | `jira: DATA-9101` |
| Status | Active |

**Payload**

```json
{
    "description": "Order reference must follow the ORD-0000 format.",
    "rule": "matchesPattern",
    "fields": ["order_ref"],
    "container_id": 145,
    "coverage": 1,
    "filter": null,
    "properties": {"pattern": "^ORD-[0-9]{4}$"},
    "tags": ["orders", "format"],
    "additional_metadata": {"jira": "DATA-9101"},
    "anomaly_message_field": null,
    "template_id": null,
    "status": "Active",
    "owner_id": 7,
    "default_anomaly_assignee_id": 12
}
```

**Sample Data**

| order_id | order_ref | channel |
| --- | --- | --- |
| 1 | ORD-4821 | web |
| 2 | 4821 | web |
| 3 | ORD-0007 | partner |
| 4 | *(null)* | web |

**What gets flagged**

Order `2` holds a bare number with no prefix. Because the expression is anchored, a value that merely contains four digits does not pass. Order `4` is NULL and passes without firing an anomaly. Coverage is 100%, so the failing row is reported as a Record Anomaly.

> **Example: Record Anomaly**
>
> order_ref has the value 4821, which does not match the required format. Values should follow the pattern: ^ORD-[0-9]{4}$

**Flowchart**

```mermaid
graph TD
    A["No filter, evaluate all rows"] --> B["Read order_ref"]
    B --> C{"Is value NULL?"}
    C -->|Yes| D["Row passes"]
    C -->|No| E{"Does it match<br/>^ORD-[0-9]{4}$?"}
    E -->|Yes| D
    E -->|No| F["Flag row.<br/>Record Anomaly per failing row."]
```

**Equivalent SQL**

```sql
-- Rows the Matches Pattern check would flag.
SELECT o.*
FROM orders o
WHERE o.order_ref IS NOT NULL
  AND o.order_ref NOT RLIKE '^ORD-[0-9]{4}$';
```

**Tab: Postal Codes for One Country, with Filter**

**The situation:** Addresses in the `US` country carry a five-digit ZIP, optionally followed by a four-digit extension. Addresses in other countries use different formats and are excluded with a filter.

**Check configuration**

| Field | Value |
| --- | --- |
| Rule | Matches Pattern |
| Field | `postal_code` |
| Filter | `country = 'US'` |
| Custom Anomaly Description | Off |
| Pattern | `^[0-9]{5}(-[0-9]{4})?$` |
| Coverage | 100% |
| Owner | *(check creator)* |
| Anomaly Assignee | *(Address Data team)* |
| Description | US addresses must carry a valid ZIP code. |
| Tags | `addresses`, `format` |
| Additional Metadata | `jira: DATA-9144` |
| Status | Active |

**Payload**

```json
{
    "description": "US addresses must carry a valid ZIP code.",
    "rule": "matchesPattern",
    "fields": ["postal_code"],
    "container_id": 512,
    "coverage": 1,
    "filter": "country = 'US'",
    "properties": {"pattern": "^[0-9]{5}(-[0-9]{4})?$"},
    "tags": ["addresses", "format"],
    "additional_metadata": {"jira": "DATA-9144"},
    "anomaly_message_field": null,
    "template_id": null,
    "status": "Active",
    "owner_id": 7,
    "default_anomaly_assignee_id": 26
}
```

**Sample Data** (filtered to `country = 'US'`)

| address_id | country | postal_code |
| --- | --- | --- |
| AD-01 | US | 94107 |
| AD-02 | US | 9410 |
| AD-03 | US | 10001-2345 |

**Why the filter matters**

The filter runs **before** the match, so addresses in other countries are never tested against the ZIP format. Only US rows are evaluated.

**What gets flagged**

`AD-02` holds four digits instead of five. `AD-03` uses the extended form, which the optional group accepts. Coverage is 100%, so the failure is reported as a Record Anomaly, and the message names the filter that scoped the evaluation.

> **Example: Record Anomaly**
>
> postal_code has the value 9410, which does not match the required format (applied to records where country = 'US'). Values should follow the pattern: ^[0-9]{5}(-[0-9]{4})?$

**Flowchart**

```mermaid
graph TD
    A["Apply filter: country = 'US'"] --> B["Read postal_code"]
    B --> C{"Does it match the ZIP pattern?"}
    C -->|Yes| D["Row passes"]
    C -->|No| E["Flag row.<br/>Message names the filter:<br/>applied to records where country = 'US'"]
```

**Equivalent SQL**

```sql
-- Rows the check would flag among US addresses.
SELECT a.*
FROM addresses a
WHERE a.country = 'US'
  AND a.postal_code IS NOT NULL
  AND a.postal_code NOT RLIKE '^[0-9]{5}(-[0-9]{4})?$';
```

**Tab: Legacy Identifier Mid-Cleanup**

**The situation:** A legacy `asset_tag` column mixes the current `AT-000000` format with values from three retired systems. A rewrite job is converting them, and a small fraction is expected to remain in the old shape until it finishes, so the check tolerates up to 0.5% failures.

**Check configuration**

| Field | Value |
| --- | --- |
| Rule | Matches Pattern |
| Field | `asset_tag` |
| Filter | *(none)* |
| Custom Anomaly Description | Off |
| Pattern | `^AT-[0-9]{6}$` |
| Coverage | 99.5% |
| Owner | *(check creator)* |
| Anomaly Assignee | *(Asset Management)* |
| Description | Asset tag must follow the AT-000000 format. |
| Tags | `assets`, `format` |
| Additional Metadata | `jira: DATA-9188` |
| Status | Active |

**Payload**

```json
{
    "description": "Asset tag must follow the AT-000000 format.",
    "rule": "matchesPattern",
    "fields": ["asset_tag"],
    "container_id": 733,
    "coverage": 0.995,
    "filter": null,
    "properties": {"pattern": "^AT-[0-9]{6}$"},
    "tags": ["assets", "format"],
    "additional_metadata": {"jira": "DATA-9188"},
    "anomaly_message_field": null,
    "template_id": null,
    "status": "Active",
    "owner_id": 7,
    "default_anomaly_assignee_id": 41
}
```

**Sample Data**

| asset_id | asset_tag | source |
| --- | --- | --- |
| AS-01 | AT-004512 | current |
| AS-02 | LEG/4512 | legacy |
| AS-03 | unknown | legacy |
| AS-04 | *(null)* | legacy |

**What gets flagged**

Assets `AS-02` and `AS-03` still carry retired formats. `AS-04` is NULL, so it passes without firing an anomaly but still counts in the scanned total. Only 50% of the rows pass, which is below the 99.5% coverage threshold, so the check reports a single Shape Anomaly for the dataset with a sample of the offending rows. Coverage below 100% does not produce Record Anomalies.

> **Example: Shape Anomaly**
>
> asset_tag values do not match the required format, affecting 2 of 4 asserted records. Values should follow the pattern: ^AT-[0-9]{6}$

**Flowchart**

```mermaid
graph TD
    A["No filter, evaluate all rows"] --> B["Read asset_tag"]
    B --> C{"Is value NULL?"}
    C -->|Yes| D["Row passes"]
    C -->|No| E{"Does it match<br/>^AT-[0-9]{6}$?"}
    E -->|Yes| D
    E -->|No| F["Flag row.<br/>Passing rate falls below the 99.5%<br/>coverage, so one Shape Anomaly is reported."]
```

**Equivalent SQL**

```sql
-- Rows the check would flag.
SELECT a.*
FROM assets a
WHERE a.asset_tag IS NOT NULL
  AND a.asset_tag NOT RLIKE '^AT-[0-9]{6}$';
```

## See Also

- **How It Works**

  The complete reference: definition, field scope, the pattern property, matching semantics, NULL handling, arrays, filter behavior, and coverage.

  [How It Works](https://userguide.qualytics.io/data-quality-checks/matches-pattern/deep-dive/how-it-works/)
- **Anomaly Reporting**

  The anomaly messages the check produces, what the numbers mean, Source Records highlighting, and Custom Anomaly Description.

  [Anomaly Reporting](https://userguide.qualytics.io/data-quality-checks/matches-pattern/deep-dive/anomaly-reporting/)
- **Best Practices**

  Guidelines for writing the expression, anchoring it, pairing rules, and keeping the signal clean.

  [Best Practices](https://userguide.qualytics.io/data-quality-checks/matches-pattern/deep-dive/best-practices/)
- **Permissions**

  The team permission each action needs: view, create, edit, archive, restore, and delete.

  [Permissions](https://userguide.qualytics.io/data-quality-checks/matches-pattern/deep-dive/permissions/)

*Last updated: September 22, 2026.*
