StephanieJoly4GitHubcubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>github-actionsAbdul RahmanFélix MalfaitReorganizing by Feature sections
Capabilities folders to give an overview of each feature
How-Tos folders to give guidance for advanced customizations
Reorganized the Developers section as well, moving the API sub section
there
added some new visuals and videos to illustrate the How-Tos articles
checked the typos, the links and added a section at the end of the
doc.json file to redirect existing links to the new ones (SEO purpose +
continuity of the user experience)
What I have not updated is the "l" folder that, per my understanding,
contains the translation of the User Guide - that I only edited in
English
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> <sup>[Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) is
generating a summary for commit
5301502a32. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: github-actions <github-actions@twenty.com>
Co-authored-by: Abdul Rahman <ar5438376@gmail.com>
Co-authored-by: Félix Malfait <felix.malfait@gmail.com>
69 lines
2.5 KiB
Plaintext
69 lines
2.5 KiB
Plaintext
---
|
|
title: Uniqueness Constraints
|
|
description: How Twenty enforces data uniqueness during import.
|
|
---
|
|
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
|
|
|
## Overview
|
|
|
|
Twenty enforces uniqueness on certain fields to prevent duplicate records and ensure data integrity. Understanding these constraints is essential for successful imports.
|
|
|
|
## Default Unique Fields
|
|
|
|
| Object | Unique Fields |
|
|
|--------|---------------|
|
|
| **People** | `id`, `email` |
|
|
| **Companies** | `id`, `domain` |
|
|
| **Custom objects** | `id` only (by default) |
|
|
|
|
<Note>The `id` field is Twenty's internal identifier, auto-generated for each record. It uses UUID format (e.g., `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).</Note>
|
|
|
|
## Custom Unique Fields
|
|
|
|
You can define additional unique fields under **Settings → Data Model**:
|
|
|
|
1. Go to **Settings → Data Model**
|
|
2. Select the object
|
|
3. Click on a field
|
|
4. Enable **Unique** in field settings
|
|
|
|
### Use Cases for Custom Unique Fields
|
|
- **External IDs**: Store IDs from other systems (Salesforce ID, HubSpot ID)
|
|
- **Business identifiers**: Employee numbers, customer codes
|
|
- **Alternative contact info**: LinkedIn profile, phone number
|
|
|
|
<Note>The field name `id` is reserved for Twenty's internal ID. Use a different name like `externalId` or `legacyId` for external identifiers.</Note>
|
|
|
|
## Import Behavior
|
|
|
|
### Creating New Records
|
|
If a unique field value doesn't exist, a new record is created.
|
|
|
|
### Updating Existing Records
|
|
If a unique field value matches an existing record, that record is **updated** with the new data.
|
|
<Warning>To **update existing records**, it is recommended to **only match one unique field**.</Warning>
|
|
|
|
### Soft-Deleted Records
|
|
|
|
<Warning>
|
|
**Deleted records count toward uniqueness.**
|
|
|
|
Soft-deleted records (visible under Command Menu → See deleted records) are included in uniqueness checks. If you import a record with the same unique value as a deleted record, the deleted record will be **restored** with the new data.
|
|
</Warning>
|
|
|
|
## Duplicate Detection During Import
|
|
|
|
During the validation phase:
|
|
- Duplicates within your file are highlighted in yellow
|
|
- You can edit or remove duplicate rows from the UI before starting the import
|
|
|
|
<VimeoEmbed videoId="1145246326" title="Video demonstration" />
|
|
|
|
## Best Practices
|
|
|
|
1. **Remove duplicates** from your file before importing
|
|
2. **Check for existing records** in Twenty before importing
|
|
3. **Use external IDs** when migrating from other systems
|
|
4. **Include unique fields** if you want to update existing records
|
|
|