# Unique Check FAQ

Source: https://userguide.qualytics.io/data-quality-checks/unique/faq/

Answers to common questions about how the Unique check evaluates uniqueness, how it handles NULLs and filters, and how anomalies are reported, grouped by topic.

## Behavior

### What happens when I select multiple fields?

The combination of values across the selected fields must be unique on every row (composite key). Individual columns can repeat values; only the **combined** tuple has to be unique. For example, a Unique check on `(order_id, line_number)` allows `order_id` to repeat and `line_number` to repeat, but the pair must be unique.

### How are NULLs treated?

Rows where every selected field is NULL are skipped, so repeated NULLs in a single field, or all-NULL composite tuples, are never reported as duplicates, the same as a SQL `UNIQUE` constraint. On a composite key, a partially NULL tuple such as `(1, NULL)` is compared like any other value, so two of them are a duplicate. Filter the optional column with `IS NOT NULL` if those should be allowed, and add a [Not Null](https://userguide.qualytics.io/data-quality-checks/not-null/introduction/) check when the field must never be empty.

### Does the filter clause run before or after the uniqueness check?

Before. The platform applies the filter first and then evaluates uniqueness only on the rows that pass the filter. This lets you scope a Unique check to a subset of records (for example, only `status = 'active'` rows) without flagging duplicates that exist outside the scope.

---

## Anomaly Reporting

### Why does the violation count include both copies of a duplicate, not just the extra one?

The platform reports every row that participates in a duplicate group as part of the violation. If `(Customer_A, 123 Main St)` appears on rows 1 and 3, both rows are flagged, not just row 3. This makes the resulting anomaly count match the rows you would see by running a `SELECT ... WHERE (a, b) IN (duplicates)` query against the source data.

### What does the Shape Anomaly message look like?

Single-field: `order_id values are repeated across N of M asserted records`

Composite key (multi-field): `order_id and line_number values are repeated across N of M asserted records`

### Why doesn't Unique produce a Record Anomaly?

Unique is a *shape*-only rule type: the violation is a property of the dataset as a whole (a duplicate group), not of an individual record's value. Other rule types (such as Min Value or Matches Pattern) can produce Record Anomalies because each row's value can be evaluated independently against the rule.

---

## Configuration

### Does Unique have any rule-specific properties?

No. The rule is fully defined by the **fields** it applies to, the **coverage**, and the optional **filter** clause, and `properties` is `null`. On an Array field, Unique compares each row's whole array with the other rows' arrays; it does not look for repeated elements inside one array, and `{"is_element_context": true}` is refused. To catch arrays that repeat an element, use a [Satisfies Expression](https://userguide.qualytics.io/data-quality-checks/satisfies-expression/introduction/) check such as `size(tags) = size(array_distinct(tags))`. See the [API](https://userguide.qualytics.io/data-quality-checks/unique/api/) page for the payload shape.

### Can I lower the coverage on a Unique check?

Yes. Coverage at 100% (`1.0`) means *every* row must be part of a unique tuple; lowering it to, say, 99.5% (`0.995`) means the check tolerates up to 0.5% of records appearing in duplicate groups before flagging an anomaly. This is useful when a small known gap of duplicates is acceptable.

### Can I combine Unique with a Not Null check on the same column?

Yes, and it is a common pattern when you want true primary-key semantics. Add a [Not Null](https://userguide.qualytics.io/data-quality-checks/not-null/introduction/) check alongside the Unique check on the same field; together they enforce the equivalent of a SQL `PRIMARY KEY` (`UNIQUE` + `NOT NULL`).

### Does Custom Anomaly Description (the `anomaly_message_field` payload field) work for Unique?

No. The Custom Anomaly Description toggle (and the corresponding `anomaly_message_field` payload field) only affects Record Anomaly messages. Because Unique emits only Shape Anomalies, the field is silently ignored at evaluation time, and the resulting anomaly message uses the fixed Shape Anomaly template described above.

### What permission do I need to create or edit a Unique 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](https://userguide.qualytics.io/data-quality-checks/unique/deep-dive/permissions/) for the full matrix.

**Still have questions?**
Contact the Qualytics support team at
[support@qualytics.ai](mailto:support@qualytics.ai).

*Last updated: October 28, 2026.*
