Uniqueness & Duplicate Detection

The Uniqueness tab helps you prevent duplicate records by defining constraints that check for matching values before records are saved.

What are Uniqueness Constraints?

Uniqueness constraints are rules that check whether a new or updated record would create a duplicate. They can:

• Block saves when duplicates are detected
• Warn about potential duplicates (see Enforcement Mode: Warn currently stops the save too)

This prevents data quality issues like duplicate contacts, duplicate invoices, or duplicate entries that can cause confusion and errors.

Accessing the Uniqueness Tab

1. Click Modules in the sidebar to open the Module catalog
2. Open your module from the catalog
3. Click the Uniqueness tab

Constraint Types

Coherence supports three types of uniqueness constraints:

Simple Unique

A single field must have unique values across all records.

Use cases:

• Email address (each contact has a unique email)
• Invoice number (no two invoices share a number)
• SKU (product identifiers must be unique)
• External ID (integration identifiers)

Composite Unique

A combination of fields must be unique together. Individual field values can repeat, but the combination cannot.

Use cases:

• First Name + Last Name + Company (same name at different companies is OK)
• Product + Variant + Size (unique SKU combinations)
• Year + Month + Sequence (date-based numbering)

Duplicate Detection Rule

Flexible OR-based rules for detecting potential duplicates. Unlike simple uniqueness, these rules support multiple matching conditions and different match types.

Use cases:

• Email matches exactly OR (First Name + Last Name + Phone) matches
• Catching likely duplicates that differ in spacing or capitalization
• Fuzzy matching with normalized values

Creating a Constraint

1. Click Add Constraint in the Uniqueness tab
2. Fill in the constraint settings:

Basic Settings

Field Selection

For Simple Unique: Select one field that must have unique values.

For Composite Unique: Select two or more fields. Check each field to include it. The combination of selected fields must be unique.

For Duplicate Detection Rules: Build rules with AND/OR logic:

• Each rule is a set of field conditions
• Multiple rules are combined with OR (match if ANY rule matches)
• Within a rule, multiple fields are combined with AND (all must match)

Match Types (Duplicate Rules Only)

Enforcement Mode

Active Toggle

Enable or disable the constraint without deleting it.

3. Click Create to save the constraint

Managing Constraints

Editing Constraints

1. Find the constraint in the list
2. Click the pencil icon
3. Update settings
4. Click Save Changes

Deleting Constraints

1. Find the constraint to remove
2. Click the trash icon
3. Confirm deletion

Disabling Constraints

Toggle the Active switch off to disable a constraint without deleting it.

Constraint Display

Each constraint shows:

Example Configurations

Unique Email Address

Unique Name per Company

Flexible Duplicate Detection

This example warns about duplicates if:

• Email matches exactly, OR
• First name AND last name AND phone all match (with fuzzy matching)

How Constraints Work

During Record Creation

1. User fills in the create form
2. Before saving, Coherence checks all active constraints
3. If a constraint matches:
   • Block: Error message, save prevented
   • Warn: "Potential duplicate record detected" error, save prevented (there is no save-anyway option in the web app today)

During Record Editing

Same behavior as creation - constraints are checked against all other records (excluding the current one).

What Gets Checked

• Only active constraints are evaluated
• Empty/null fields are typically skipped in matching
• Matching is done according to the specified match type

Best Practices

Start with Essential Uniqueness

Begin with the most important unique identifiers:

• Email addresses
• Invoice/order numbers
• External system IDs
• Product SKUs

Use Appropriate Enforcement

• Block for true business keys (invoice numbers, IDs)
• Because Warn currently stops the save as well, only add a constraint when a match really is a duplicate

Consider User Experience

Every active constraint, Block or Warn, can stop a save today. Keep constraints to values that should never repeat, and prefer exact identifiers such as email over loose matches such as names.

Name Constraints Clearly

Good names help users understand constraint errors:

• ✅ "Unique Email Address"
• ✅ "One Contact per Company"
• ❌ "Constraint 1"

Test with Real Data

Create test records to verify constraints work as expected before publishing the module.

---

Related: Configuring Fields | Module Builder Guide