Impact Metrics¶

Impact metrics measure how big a check's failure is in terms that matter to your business, such as the total amount of the failed orders or how many different customers they affect. Each metric turns the records that failed the check into one number, measured every time the check fails in a scan.

You can also give a metric an expected range. When a failure takes the metric outside its range, Qualytics raises the impact of the anomaly and can tag it, so the anomaly stands out in triage and can start a Flow.

Which Checks Offer Impact Metrics¶

Impact metrics are available on checks that flag individual records, such as Not Null, Between, Matches Pattern, or Exists In, and on Unique, where the failed records are the duplicates. Checks that test the table or file as a whole, or a total across it, such as Expected Schema, Freshness, Volumetric, Sum, or Distinct Count, have no failed records to measure, so their form has no Impact section.

Add an Impact Metric¶

Open the check's form and go to the Impact section, above Ownership. Click Add your first impact metric, or Add Impact Metric to add another. A check can have up to 10 impact metrics.

Each metric is defined in one of two ways, chosen at the top of the metric:

Guided: pick what you want to know and the field to measure.
Expression: write one calculation over the failed records, such as a sum or a count.

Field	Required	Description
What do you want to know? (Guided)		What the metric measures across the failed records. See the options below.
Field (Guided)		The field to measure. It can be any field of the table or file, not only the one the check tests.
Expression (Expression)		One calculation over the failed records, using any field of the table or file. A metric written through the API shows its SQL here, and can only be edited through the API.
Name		The name shown wherever the metric appears.
Show value as		How the value reads. See Show Value As. Ages always read in days, so age metrics don't offer it.
Expected range		The Minimum and Maximum the metric should stay between. Set either or both. Once the check has failed in a scan, the last value measured and its date appear below the range.
Tag the anomaly when out of range		A toggle. Turn it on and pick one or more tags to add to the anomaly when the metric is outside its expected range. Available once a minimum or maximum is set.
Filter the failed records		A toggle. Turn it on to measure only the failed records that match a condition, for example `amount > 100`.

The Guided options are:

Option	What it measures	Field types
Total value affected	Adds up a number field, counting negative values as positive.	Number
Number of different values	Counts each different value of a field once, for example the customers affected.	Any field that isn't nested
Average value	The average of a number field.	Number
Largest value	The largest value of a number field.	Number
Average age	How many days old the failed records are, on average.	Date or timestamp
Age of the oldest	How many days old the oldest failed record is.	Date or timestamp

Show Value As¶

Show value as formats the number. Leave it empty to show the full number. Use these placeholders, with any text around them:

Format	Reads as
`{{value}}`	The full number, for example 1,234,567.89
`{{short}}`	The number abbreviated, for example 1.23M
`${{short}}`	$1.23M
`{{value}} kg`	1,234,567.89 kg

Outside the Expected Range¶

What the range is compared with depends on the anomaly type. A Shape anomaly measures the metric across all the records that failed the check in the scan. A Record anomaly measures it for that one record only. For example, if 100 failed orders each total $20, the Shape anomaly shows $2,000, while each Record anomaly shows $20, so a $1,000 maximum flags the Shape anomaly but none of the Record anomalies. Set the range for the anomalies you want to catch.

When a metric is outside its expected range in the scan that found the anomaly:

The anomaly's impact is at least High, and a metric far outside its range can make it Critical. See How Impact Is Decided.
The metric is marked on the anomaly, for example Above its limit of $1M.
The anomaly gets the tags you picked, if any, so Flows and filters that use those tags catch it.

Where Impact Metrics Appear¶

Failed Checks: on the anomaly, each failed check with impact metrics shows a button next to its impact, reading how many metrics it measured or how many are outside their range (for example, 1 outside). Click it to see each value. See Anomaly Insights.
Anomaly description: the default description lists each failed check's metrics and values in an Impact block under the check. See Anomaly Description.
Impact explanation: when a metric decided the anomaly's impact, hovering the impact shows it under Impact metrics.

A value of -- means no failed record had anything to measure in that scan. Couldn't measure means the metric failed to run; hover over it to see why.

An anomaly keeps the metric names and values it was found with. Renaming or removing a metric later changes only future anomalies.

Impact Metrics in the API¶

A check's impact metrics are its impact_metrics field. Send it on POST /api/quality-checks and PUT /api/quality-checks/{id}, next to the rest of the check described on each rule type's API page. Checks that have impact metrics return the same field when you read them.

Field	Required	Description
`id`		Identifies the metric within the check: letters, digits, and underscores, starting with a letter or an underscore, up to 64 characters. Results are recorded against it, so keep it when you rename the metric.
`name`		The name shown wherever the metric appears.
`sql`		A Spark SQL query over `failed_rows`, the records that failed the check, that returns one row holding one number. For example, `SELECT try_sum(abs(amount)) AS value FROM failed_rows`. A `WHERE` clause measures only some of the failed records.
`pattern`		How the value reads, with the placeholders of Show Value As.
`limit`		The expected range: `min`, `max`, or both, and optionally `anomaly_additional_tags`, the names of the tags added to the anomaly when the value is outside the range.
`guided`		The Guided choices the form built the SQL from. Leave it out when you write the SQL yourself.

Measure the total amount of the failed orders and tag the anomaly above $1M

Add the field to the body you send to create or update the check:

{
  "impact_metrics": [
    {
      "id": "total_amount",
      "name": "Total amount",
      "sql": "SELECT try_sum(abs(`amount`)) AS value FROM failed_rows",
      "pattern": "${{short}}",
      "limit": {
        "max": 1000000,
        "anomaly_additional_tags": ["finance-review", "high-value"]
      }
    }
  ]
}

A check takes up to 10 metrics, and each id can appear only once.
On a PUT, leaving impact_metrics out keeps the current metrics. Send [] to remove them all.
A rule type without failed records to measure, such as Sum, refuses the field with a 422. So does a limit with neither min nor max, a min above the max, or an external tag in anomaly_additional_tags.