snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/user-guide/data-model/capabilities/fields.mdx

@@ -0,0 +1,118 @@
+---
+title: Fields
+description: Understand the role of fields and how to manage them.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+
+## About Fields
+
+Fields are like columns in a spreadsheet. They store different types of data like text, numbers, or dates. Fields can be standard (built-in) or custom (the ones you create).
+
+### Standard Fields
+
+Standard fields come built-in with Twenty to handle common business needs.
+
+For example, `First Name` and `Last Name` are standard fields in the `People` object. They store text data for individual names.
+
+You cannot delete standard fields, but you can deactivate them if you don't need them.
+
+You can also customize the options of the standard `SELECT` type fields, for example the options for the `Stage` on Opportunities.
+
+<img src="/images/user-guide/fields/standard-fields.png" style={{width:'100%'}}/>
+
+### Custom Fields
+
+Custom fields can be added to any object. You can store text, numbers, dates, dropdown selections, and more. Use custom fields to track information that's specific to your business.
+
+For instance, a custom field for SpaceX could be `Rocket Active Status`, indicating if a rocket is operational.
+
+<img src="/images/user-guide/fields/custom-fields.png" style={{width:'100%'}}/>
+
+## Field Types
+
+Twenty supports various field types:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| Address | Structured address with street, city, state, country, postal code | Office Address |
+| Array | List of text values | Tags |
+| Boolean | True/false checkbox | Is Active |
+| Currency | Monetary value with currency code | Deal Amount (USD) |
+| Date | Date values | Close Date |
+| Date & Time | Date with time | Meeting Time |
+| Domain | Website domain (used for Companies) | acme.com |
+| Email | Email addresses (with primary + additional) | Contact Email |
+| JSON | Structured JSON data | Custom metadata |
+| Links | URLs with labels (primary + secondary) | Website, LinkedIn |
+| Long Text | Multi-line text | Description, Notes |
+| Multi-Select | Multiple choices from a predefined list | Tags, Categories |
+| Number | Numeric values (integers or decimals) | Quantity, Score |
+| Phone | Phone numbers with country code | Work Phone |
+| Rating | Star rating (1-5) | Priority, Score |
+| Relation | Links to records in other objects | Company → People |
+| Select | Single choice from a predefined list | Stage, Status |
+| Text | Single line of text | Name, Title |
+
+## Create a Custom Field
+
+To add a custom field to any object, follow these steps:
+1. Go to `Settings` in the left sidebar.
+2. Go to `Data Model`, then select the object you wish to customize.
+3. Proceed by clicking on `+ New Field`.
+4. Choose a field name and type that suits your requirements. Consider adding a field description for better understanding.
+
+Your newly created field is now available within the application's fields. To display it on a specific view, click on the options menu, then select `Fields`.
+
+<VimeoEmbed videoId="927628219" title="Video demonstration" />
+
+**Quick way:** Click the **+** button at the top right of any object table, then select `Customize fields`. This takes you directly to the Data Model settings.
+
+<img src="/images/user-guide/fields/quick-new-field.png" style={{width:'100%'}}/>
+
+## Deactivate a Field
+
+You can deactivate a field to hide it from the app without losing your data. Think of it as hiding the field rather than deleting it.
+
+Here's how you can do it:
+
+1. Find the field you want to deactivate in your object settings.
+2. Click the three dots `⋮` next to the field to open the menu.
+3. Select `Deactivate` from the dropdown.
+
+<img src="/images/user-guide/fields/deactivate-field.png" style={{width:'100%'}}/>
+
+What happens when you deactivate a field?
+
+1. **In the app:** The field disappears and you can't add new values to it.
+2. **Existing relationships:** If it's a relation field, existing connections stay, but you can't create new ones.
+3. **API access:** You can still access the field and its data through the API.
+
+You can reactivate Standard and Custom Fields or have the option to permanently delete them.
+
+## Make Fields Unique
+
+Make a field unique to ensure distinct records cannot have the same value. For example, email addresses are unique for each person.
+
+If you get an error when setting uniqueness, check for duplicate values in your data (including deleted records).
+
+## Indexes (Advanced)
+
+Database indexes are managed automatically — adding your own is rarely necessary and easy to get wrong. With Advanced mode on, each object has an **Indexes** section under `Settings → Data Model → <object>` for the cases where you know you need one.
+
+## Field Configuration Best Practices
+
+### Naming Conventions and Limitations
+- **Singular and plural names must be distinct**: Our GraphQL API needs distinct names for mutations
+- **Protected field names**: some names are reserved for system usage (e.g., `Type`, `Application`)
+
+### Currency and Phone Fields
+- **Default currency**: can be configured via the data model
+- **Default country codes**: can be configured for phone fields via the data model
+
+### Select Fields
+- **A default option can be selected** for each Select field
+
+### Record Text Fields
+- **Each object has one main display field**: This field appears in the leftmost column and represents the record when linked to other objects. It must be a text field. For example, People uses `Name` as the main field, so when you link a person to a company, you'll see their name in the company's view.

packages/twenty-docs/user-guide/data-model/capabilities/objects.mdx

@@ -0,0 +1,86 @@
+---
+title: Objects
+description: Learn about standard and custom objects in Twenty.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+
+## Standard Objects
+
+Standard objects are predefined entities in your workspace to help you get started. They're part of a shared data model accessible to all users of Twenty. You can use them as-is, customize them or deactivate them.
+
+<img src="/images/user-guide/objects/standard-objects.png" style={{width:'100%'}}/>
+
+### People
+
+The `People` object stores your contacts. It includes contact details and interaction history, so you can see all your customer interactions in one place.
+
+### Companies
+
+The `Companies` object stores your business accounts. It includes details like industry, size and location. Companies connect to both `People` and `Opportunities` objects.
+
+### Opportunities
+
+The `Opportunities` object stores deal-related data. It tracks the progression of potential sales, from prospecting to closure, recording stages, deal sizes, associated account, and expected close date. You can view your sales pipeline in a kanban layout.
+
+### Notes
+
+The `Notes` object stores free-form notes that can be attached to People, Companies, Opportunities, and other records. Use notes to capture meeting summaries, important details, or any contextual information.
+
+### Tasks
+
+The `Tasks` object stores to-dos and action items. Tasks can be linked to People, Companies, Opportunities, and other records. Track due dates, assignees, and completion status to stay on top of your follow-ups.
+
+## Custom Objects
+
+Custom objects let you store information that's unique to your organization and that standard objects can't handle. For example, if you're SpaceX, you may want to create a custom object for Rockets and Launches.
+
+<img src="/images/user-guide/objects/custom-objects.png" style={{width:'100%'}}/>
+
+### Creating a New Custom Object
+
+To create a new custom object:
+
+1. Go to Settings in the sidebar on the left.
+2. Under Workspace, go to Data Model. Here you'll be able to see an overview of all your existing Standard and Custom objects (both active and deactivated).
+
+<VimeoEmbed videoId="926288174" title="Video demonstration" />
+
+3. Click on `+ New object` at the top. Enter the name (both singular and plural), choose an icon, and add a description for your custom object and hit Save (at the top right). Using Listing as an example of custom object, the singular would be "listing" and the plural would be "listings" along with a description like "Listings that hosts created to showcase their property."
+4. Your custom object is now created and will appear in your sidebar. You can start adding records to it right away.
+
+## Managing Objects
+
+### Deactivating Objects
+If you don't need a standard or custom object:
+1. Go to Settings → Data Model
+2. Find the object you want to deactivate and click it
+3. Go to object's **Settings** tab
+4. Click `Deactivate` button
+5. The object will be hidden from your workspace but data is preserved
+
+### Reactivating Objects
+To bring back a deactivated object:
+1. Go to Settings → Data Model
+2. Enable `Deactivated` filter
+3. Look for deactivated objects (they have `Deactivated` next to their name)
+4. Click `⋮` and then `Activate` to reactivate it
+5. The object and all its data will be restored
+
+## Best Practices
+
+### When to Create Custom Objects
+- **Unique business entities**: Things specific to your industry or process
+- **Complex relationships**: When you need to track connections between multiple entities
+- **Scalable data**: When you might have many instances of something
+
+### When to Use Fields Instead
+- **Simple attributes**: Properties that describe existing objects
+- **Categories or labels**: Ways to classify existing records
+- **Single values**: Information that doesn't need its own lifecycle
+
+### Object Naming
+- **Use clear, descriptive names**: Make it obvious what the object represents
+- **Follow conventions**: Use singular for the object name, plural for the collection
+- **Consider your team**: Choose names everyone will understand

packages/twenty-docs/user-guide/data-model/capabilities/relation-fields.mdx

@@ -0,0 +1,88 @@
+---
+title: Relation Fields
+description: Connect records across different objects using relation fields.
+---
+
+## Types of Relations
+
+### One-to-Many
+One record in Object A can be linked to many records in Object B.
+
+**Example:** One Company can have many People (employees).
+
+### Many-to-One
+Many records in Object A can be linked to one record in Object B.
+
+**Example:** Many People can belong to one Company.
+
+### Relations to Multiple Object Types
+
+Some objects can link to multiple object types on one side of the relation.
+
+**Example:** A Note can be attached to one Person AND one Company AND one Opportunity simultaneously. The Note is on the "many" side, connecting to multiple "one" sides.
+
+<img src="/images/user-guide/fields/many-to-one-morph.png" style={{width:'100%'}}/>
+
+Similarly, a Project (on the "one" side) could receive links from multiple People, multiple Companies, and multiple Notes.
+
+<img src="/images/user-guide/fields/one-to-many-morph.png" style={{width:'100%'}}/>
+
+<Warning>
+**Import/Export limitation**: Relations pointing to multiple object types are not yet supported for CSV import/export. This is on our roadmap.
+</Warning>
+
+### Many-to-Many
+
+Many records in Object A can be linked to many records in Object B.
+
+**Example:** Many People can be linked to many Projects, and vice versa.
+
+Many-to-many relations use a **junction object** pattern: an intermediate object that connects both sides. With the junction relation feature, Twenty displays the final linked records directly, hiding the intermediate object from the UI.
+
+<Warning>
+**Beta Feature**: Junction relations must be enabled at **Settings → Community → Features** before use.
+</Warning>
+
+See [How to Create Many-to-Many Relations](/user-guide/data-model/how-tos/create-many-to-many-relations) for a complete step-by-step guide.
+
+## Creating a Relation Field
+
+1. Go to **Settings → Data Model**
+2. Select the object where you want to add the relation
+3. Click **+ New field**
+4. Select **Relation** as the field type
+5. Choose the target object(s) to relate to
+6. Configure the relation settings:
+   - **Field name on source object**: The name of the relation field on the object you're editing
+   - **Field name on destination object**: The name of the relation field that will appear on the target object
+   - Relation type (one-to-many, many-to-one)
+7. Click **Save**
+
+## Standard Relations
+
+Twenty comes with pre-built relations between standard objects:
+
+| From Object | To Object | Relation Type |
+|-------------|-----------|---------------|
+| People | Companies | Many-to-One |
+| Opportunities | Companies | Many-to-One |
+| Opportunities | People  | Many-to-One |
+
+## Best Practices
+
+### Planning Relations
+- **Map your data model**: Plan relations before creating them
+- **Consider direction**: Think about which object "owns" the relationship
+- **Avoid circular dependencies**: Keep your data model clean
+
+### Naming Relations
+- **Use clear names**: Make it obvious what the relation represents
+- **Be consistent**: Use similar naming patterns across relations
+- **Consider both sides**: Name both sides of the relation appropriately
+
+### Performance
+- **Don't over-relate**: Too many relations can slow down your workspace
+
+## Limitations
+- **Deleting relations** removes the link but not the related records
+- **Circular relations** should be avoided for data integrity

packages/twenty-docs/user-guide/data-model/how-tos/create-custom-fields.mdx

@@ -0,0 +1,71 @@
+---
+title: Create Custom Fields
+description: Step-by-step guide to adding custom fields to any object.
+---
+
+Custom fields let you capture information specific to your business. Add them to any object—standard or custom.
+
+## Steps
+
+1. Go to **Settings → Data Model**
+2. Select the object you want to add a field to
+3. Click **+ New Field**
+4. Choose a **field type** (see [Fields](/user-guide/data-model/capabilities/fields) for all types)
+5. Enter the **field name** and optional description
+6. Configure field-specific settings (see below)
+7. Click **Save**
+
+**Quick method:** Click the **+** at the end of column headers in any table view → **Customize fields**.
+
+## Show the Field in Views
+
+New fields aren't automatically visible. To display:
+1. Open the object's table view
+2. Click **Options → Fields**
+3. Click the **eye icon** next to your field to show it
+4. Drag to reorder
+
+## Configuration Options
+
+### For Select / Multi-Select
+
+1. Click **+ Add option** to create choices
+2. Set a **default option** if desired
+3. Drag to reorder options
+
+<Note>
+**Use API names for imports.** Enable **Advanced mode** in Settings to see API names. See [Field Mapping](/user-guide/data-migration/capabilities/field-mapping).
+</Note>
+
+### For Currency Fields
+
+Set the **default currency** (USD, EUR, etc.) for new records.
+
+### For Phone Fields
+
+Set the **default country code** to pre-fill for new phone numbers.
+
+### Making a Field Unique
+
+Toggle **Unique** to prevent duplicate values across records.
+
+<Note>
+If duplicates exist (including in deleted records), you'll get an error. Clean up duplicates first.
+</Note>
+
+### Setting Default Values
+
+For Select fields, you can choose which option is pre-selected for new records. For Checkbox fields, set whether it's checked or unchecked by default.
+
+## Deactivating a Field
+
+1. Go to **Settings → Data Model**
+2. Find the field
+3. Click **⋮ → Deactivate**
+
+Data is preserved. You can reactivate or permanently delete later.
+
+## Related
+
+- [Fields](/user-guide/data-model/capabilities/fields) — all field types explained
+- [Data Model FAQ](/user-guide/data-model/how-tos/data-model-faq) — common questions

packages/twenty-docs/user-guide/data-model/how-tos/create-custom-objects.mdx

@@ -0,0 +1,50 @@
+---
+title: Create Custom Objects
+description: Step-by-step guide to creating custom objects in Twenty.
+---
+
+Custom objects let you store information unique to your business that standard objects don't cover. For example: Projects, Products, Tickets, or Listings.
+
+<Note>
+**Not sure if you need an object or a field?** See [Understanding Your Data Model](/user-guide/data-model/overview) for guidance.
+</Note>
+
+## Steps
+
+1. Go to **Settings → Data Model**
+2. Click **+ Add object**
+3. Fill in:
+   - **Singular name** (e.g., "Listing")
+   - **Plural name** (e.g., "Listings")
+   - **Icon**
+   - **Description** (optional)
+4. Click **Save**
+
+Your object appears in the sidebar immediately.
+
+## Next: Add Fields
+
+New objects start with basic fields. Add custom fields to capture the data you need:
+
+1. In **Settings → Data Model**, select your object
+2. Click **+ New Field**
+3. Choose a field type, configure, and save
+
+See [How to Create Custom Fields](/user-guide/data-model/how-tos/create-custom-fields) for details on field types and configuration.
+
+## Connecting to Other Objects
+
+To link your object to People, Companies, or other objects, create a relation field. See [How to Create Relation Fields](/user-guide/data-model/how-tos/create-relation-fields).
+
+## Deactivating an Object
+
+If you no longer need an object:
+1. Go to **Settings → Data Model → object of your choice → Settings**
+2. Click the **Deactivate** button
+
+The object is hidden but data is preserved. You can reactivate or permanently delete later.
+
+## Related
+
+- [Objects](/user-guide/data-model/capabilities/objects) — standard vs custom objects
+- [Data Model FAQ](/user-guide/data-model/how-tos/data-model-faq) — common questions

packages/twenty-docs/user-guide/data-model/how-tos/create-many-to-many-relations.mdx

@@ -0,0 +1,170 @@
+---
+title: Create Many-to-Many Relations
+description: Connect records where many items on both sides can be linked together using junction objects.
+---
+
+Many-to-many relations let you connect multiple records on both sides. For example: many People can work on many Projects, and each Project can have many People.
+
+<Warning>
+**Beta Feature**: Junction relations are currently in beta. Enable them at **Settings → Community → Features** before following this guide.
+</Warning>
+
+<Note>
+This feature also requires **Advanced mode** to be enabled (toggle at the bottom left of Settings).
+</Note>
+
+## When to Use Many-to-Many
+
+Use many-to-many when both sides of a relationship can have multiple connections:
+
+| Relationship | Example |
+|-------------|---------|
+| People ↔ Projects | A person works on multiple projects; a project has multiple team members |
+| Companies ↔ Tags | A company can have multiple tags; a tag can apply to multiple companies |
+| Products ↔ Orders | A product can be in multiple orders; an order contains multiple products |
+
+## How It Works
+
+Twenty uses a **junction object** pattern for many-to-many relations. A junction object sits between two objects and holds the connections:
+
+```
+People ←→ Project Assignments ←→ Projects
+```
+
+The **Project Assignments** object (junction) has:
+- A relation to People (many-to-one)
+- A relation to Projects (many-to-one)
+
+When you enable the junction relation toggle, Twenty displays linked records directly instead of showing the intermediate junction records.
+
+## Prerequisites
+
+1. **Enable Junction Relations in Beta Features**: Go to **Settings → Community → Features** and enable **Junction Relations**
+2. **Enable Advanced mode**: Toggle on **Advanced mode** at the bottom left of the Settings sidebar
+3. Plan your data model:
+   - Which two objects are you connecting?
+   - What should the junction object be called?
+
+## Step 1: Create the Junction Object
+
+First, create the intermediate object that will hold the connections.
+
+1. Go to **Settings → Data Model**
+2. Click **+ Add object**
+3. Name it descriptively (e.g., "Project Assignment", "Team Member", "Product Order")
+4. Toggle "Skip creating a Name field" on
+
+<img src="/images/user-guide/fields/new-pivot-object.png" alt="New pivot object" />
+
+5. Click **Save**
+
+<Tip>
+**Naming convention**: Use a name that describes the relationship, like "Project Assignment" or "Team Membership". This makes the data model easier to understand.
+</Tip>
+
+## Step 2: Create Relations Between Objects and the Junction
+
+Add relation fields from each of your two objects to the junction object.
+
+### First Relation (Object A → Junction)
+
+1. Select your first object in **Settings → Data Model**
+2. Click **+ Add Relation**
+3. Select the junction object (e.g., "Project Assignments")
+4. Set the relation type to **One-To-Many** (one person can link to many assignments)
+5. Name the fields:
+    - Field on People: e.g., "Project Assignments"
+    - Field on junction: e.g., "Person"
+6. Click **Save**
+
+### Second Relation (Object B → Junction)
+
+1. Select your second object in **Settings → Data Model**
+2. Click **+ Add Relation**
+3. Select the junction object (e.g., "Project Assignments")
+4. Set the relation type to **One-To-Many** (one project can link to many assignments)
+5. Enable **"This is a relation to a Junction Object"**
+
+<img src="/images/user-guide/fields/junction-relation-toggle.png" style={{width:'100%'}}/>
+
+6. Name the fields:
+   - Field on junction: e.g., "Project"
+   - Field on Projects: e.g., "Team Members"
+7. Click **Save**
+
+## Step 3: Configure the Junction Relation Display
+
+Now configure the source objects to display linked records directly, skipping the intermediate junction object.
+
+1. Go to **Settings → Data Model**
+2. Select the first object (e.g., "People")
+3. Find the relation field pointing to the junction object (e.g., "Project Assignments")
+4. Click to edit the field
+5. Enable **"This is a relation to a Junction Object"**
+6. Select the **Target relation** (e.g., "Project" — the field on the junction that points to the other side)
+7. Click **Save**
+
+## Result
+
+After configuration:
+
+- On a **Person** record, the "Project Assignments" field displays **Projects** directly (not assignment records)
+- On a **Project** record, the "Team Members" field displays **People** directly
+
+The junction object still exists and stores the connections, but the UI presents a cleaner many-to-many view.
+
+## Example: People ↔ Projects
+
+Here's a complete walkthrough:
+
+### Create the Junction Object
+- Name: **Project Assignment**
+- Description: "Links people to projects they work on"
+
+### Add Relations
+1. **People → Project Assignment**
+   - Type: One-to-Many
+   - Field on People: "Project Assignments"
+   - Field on Assignment: "Person"
+
+2. **Projects → Project Assignment**
+   - Type: One-to-Many
+   - Field on Projects: "Team Members"
+   - Field on Assignment: "Project"
+
+### Configure Junction Display
+1. On **People** object:
+   - Edit "Project Assignments" field
+   - Enable junction toggle
+   - Target: "Project"
+
+2. On **Projects** object:
+   - Edit "Team Members" field
+   - Enable junction toggle
+   - Target: "Person"
+
+### Use It
+- Open a Person record → See their Projects directly
+- Open a Project record → See team members directly
+- Create new connections from either side
+
+## Adding Extra Data to Connections
+
+Since the junction object is a real object, you can add custom fields to store information about the relationship:
+
+- **Role**: "Developer", "Designer", "Manager"
+- **Start Date**: When the person joined the project
+- **Hours Allocated**: Weekly hours on this project
+
+To access this data, navigate to the junction object directly or query it via the API.
+
+## Limitations
+
+- **CSV Import/Export**: Importing many-to-many relations directly is not supported. Import records to the junction object instead.
+- **Filters**: Filtering by many-to-many relations may have limited options.
+
+## Related
+
+- [Relation Fields](/user-guide/data-model/capabilities/relation-fields) — relation types explained
+- [Create Custom Objects](/user-guide/data-model/how-tos/create-custom-objects) — how to create objects
+- [Create Relation Fields](/user-guide/data-model/how-tos/create-relation-fields) — basic relation setup

packages/twenty-docs/user-guide/data-model/how-tos/create-relation-fields.mdx

@@ -0,0 +1,69 @@
+---
+title: Create Relation Fields
+description: Step-by-step guide to connecting objects with relation fields.
+---
+
+Relation fields connect records from different objects—for example, linking People to Companies.
+
+<Note>
+**Relation names cannot be changed after creation** (they affect the API). Plan your names carefully.
+</Note>
+
+## Before You Start
+
+Decide:
+- Which objects are you connecting? (e.g., People → Companies)
+- Which is the "one" side? (e.g., Company)
+- Which is the "many" side? (e.g., People — many people work at one company)
+- What should the field be named on each side?
+
+See [Relation Fields](/user-guide/data-model/capabilities/relation-fields) for relation types explained.
+
+## Steps
+
+1. Go to **Settings → Data Model**
+2. Select the object where you want the relation (typically the "many" side)
+3. Click **+ New Field**
+4. Select **Relation** as the field type
+5. Choose the **target object**
+6. Select **One-to-Many** or **Many-to-One**
+7. Enter field names for **both sides** of the relation
+8. Click **Save**
+
+## Example: People → Companies
+
+- Go to **Settings → Data Model → People**
+- Add a Relation field
+- Target: **Companies**
+- Type: **Many-to-One**
+- Field on People: **Company**
+- Field on Companies: **Employees**
+
+Now each Person can be linked to a Company, and each Company shows its People.
+
+## Deactivating a Relation
+
+1. Go to **Settings → Data Model → object of your choice**
+2. Find the relation field and click it
+3. Click **Deactivate** button
+
+Links are preserved but hidden. Reactivate to restore.
+
+<Note>
+**Deactivating a relation doesn't delete records.** Only the link between them is removed.
+</Note>
+
+## Deleting a Relation
+
+1. Go to **Settings → Data Model → object of your choice**
+2. Find the relation field and click it
+3. Click **Delete** button
+
+<Note>
+Applies only to custom relations. Standard relations can only be deactivated.
+</Note>
+
+## Related
+
+- [Relation Fields](/user-guide/data-model/capabilities/relation-fields) — types and limitations
+- [How to Import Relations](/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) — bulk import linked records

packages/twenty-docs/user-guide/data-model/how-tos/customize-your-data-model.mdx

@@ -0,0 +1,22 @@
+---
+title: Customize Your Data Model
+description: Overview of data model customization options.
+---
+
+Twenty's data model is fully customizable. Create objects, fields, and relations to match your business.
+
+## Quick Links
+
+| I want to... | Guide |
+|--------------|-------|
+| Create a new object | [How to Create Custom Objects](/user-guide/data-model/how-tos/create-custom-objects) |
+| Add fields to an object | [How to Create Custom Fields](/user-guide/data-model/how-tos/create-custom-fields) |
+| Connect objects together | [How to Create Relation Fields](/user-guide/data-model/how-tos/create-relation-fields) |
+
+## Learn More
+
+- [Understanding Your Data Model](/user-guide/data-model/overview) — key concepts and planning tips
+- [Objects](/user-guide/data-model/capabilities/objects) — standard vs custom objects
+- [Fields](/user-guide/data-model/capabilities/fields) — all field types
+- [Relation Fields](/user-guide/data-model/capabilities/relation-fields) — connecting objects
+- [Data Model FAQ](/user-guide/data-model/how-tos/data-model-faq) — common questions

packages/twenty-docs/user-guide/data-model/how-tos/data-model-faq.mdx

@@ -0,0 +1,157 @@
+---
+title: Data Model FAQ
+description: Frequently asked questions about Twenty's data model.
+---
+
+## Object Management
+
+<AccordionGroup>
+<Accordion title="Can I delete a custom object?">
+Yes, custom objects can be deleted. You can also deactivate them first, which hides the object and its data from the interface while preserving the data.
+</Accordion>
+
+<Accordion title="Can I delete standard objects (People, Companies, etc.)?">
+No, standard objects cannot be deleted. You can only deactivate them, which hides them from the interface but preserves the data.
+</Accordion>
+
+<Accordion title="How many custom objects can I create?">
+You can create as many custom objects and fields as you need — the price doesn't change.
+</Accordion>
+
+<Accordion title="Can I rename a standard object?">
+You can rename the label of standard objects (People, Companies, Opportunities), but not their API names. The API names are fixed for consistency across all Twenty workspaces.
+</Accordion>
+
+<Accordion title="Can I change an object's icon?">
+Yes, you can change the icon for both standard and custom objects in **Settings → Data Model**.
+</Accordion>
+
+<Accordion title="Can I reorder objects in the sidebar?">
+Yes. With the **Layouts** permission, enter sidebar customization mode to drag and drop items in the **Workspace** section. This order is shared across the workspace. Items in **Favorites** are personal to each user and can be reordered without entering customization mode. See the [Sidebar guide](/user-guide/layout/capabilities/navigation).
+</Accordion>
+
+<Accordion title="Can I hide objects from the sidebar?">
+You can hide objects you don't use from the sidebar without deleting them. You can show them again from **Settings → Data Model**. See the [Sidebar guide](/user-guide/layout/capabilities/navigation).
+</Accordion>
+</AccordionGroup>
+
+## Field Capabilities
+
+<AccordionGroup>
+<Accordion title="Can I change a field type after creation?">
+No, field types cannot be changed after creation. If you need a different type, create a new field with the correct type, migrate your data, then deactivate the old field.
+</Accordion>
+
+<Accordion title="Why do I need different singular and plural names?">
+Our GraphQL API uses both forms for different operations:
+- `createPerson` (singular) for single record actions
+- `createPeople` (plural) for bulk operations
+
+This creates limitations when singular and plural forms are the same, but it improves the developer experience.
+</Accordion>
+
+<Accordion title="Why are some field names protected?">
+Certain field names like `Type` or `Application` are reserved for system use. Choose alternative names like `Category` or `Classification` instead.
+</Accordion>
+
+<Accordion title="What happens when I deactivate a field?">
+- The field is hidden from the interface
+- Existing data is preserved
+- You can still access the field via API
+- Existing relations remain but you can't create new ones
+- You can reactivate the field later
+</Accordion>
+
+<Accordion title="Can I make a field required?">
+Currently, you cannot make custom fields required. All fields accept empty values. You can use workflows to enforce required fields by sending alerts or blocking actions when fields are empty.
+</Accordion>
+
+<Accordion title="What's the difference between unique and required?">
+- **Unique**: No two records can have the same value in this field
+- **Required**: The field must have a value (not currently supported for custom fields)
+</Accordion>
+
+<Accordion title="Can I create formula fields?">
+Formula fields are coming in **H2 2026**. In the meantime, you can use workflows to calculate and update field values automatically.
+</Accordion>
+
+<Accordion title="Can I have nested fields in my objects?">
+Nested fields are coming in **H2 2026**. Currently, you can use workflows to bring field values from related objects. For example, to display a company's industry on a Person record, create a custom field on People and use a workflow to synchronize the value.
+</Accordion>
+
+<Accordion title="Can I reorder fields in objects?">
+Yes, go to Settings → Data model → object of your choice → Layout and click **Customize record page**. If this button is disabled, you must create a record.
+</Accordion>
+</AccordionGroup>
+
+## Relations
+
+<AccordionGroup>
+<Accordion title="Can I have a relation pointing to the same object?">
+Yes! Self-referencing relations are supported and recommended for use cases like account hierarchies. For example, create a relation from Companies to Companies to track parent/child accounts.
+</Accordion>
+
+<Accordion title="Can I create many-to-many relationships?">
+Many-to-many relationships are coming in **H2 2026**. Currently, create an intermediate object with two one-to-many relationships as a workaround.
+
+For example, to link People and Projects (many-to-many), create a "Project Assignments" object with:
+- A relation to People (many assignments → one person)
+- A relation to Projects (many assignments → one project)
+</Accordion>
+
+<Accordion title="What are relations to multiple object types (Morph relationships)?">
+These allow one object to relate to multiple different object types through a single field. For example, Notes can be attached to People AND Companies AND Opportunities simultaneously.
+
+Each Note links to one Person, one Company, and one Opportunity at the same time.
+
+Learn more in [Relation Fields](/user-guide/data-model/capabilities/relation-fields).
+</Accordion>
+
+<Accordion title="Can I have multiple relations between the same objects?">
+Yes, you can create multiple relations between the same two objects. For example, a Company could have both a "Primary Contact" and "Billing Contact" relation to People.
+</Accordion>
+
+<Accordion title="What happens to relations when I delete a record?">
+When you delete a record, the relation link is removed from the related records. The related records themselves are not deleted.
+</Accordion>
+
+<Accordion title="Can I create circular relations?">
+While technically possible, circular relations (A → B → C → A) should be avoided as they can cause confusion and potential performance issues.
+</Accordion>
+</AccordionGroup>
+
+## Access and Permissions
+
+<AccordionGroup>
+<Accordion title="Where can I see and edit my data model?">
+Go to **Settings → Data Model** to view and edit all your objects and fields.
+</Accordion>
+
+<Accordion title="Why can't I see the Data Model under Settings?">
+Reach out to your workspace administrator. Data model access is usually restricted to administrators only.
+</Accordion>
+</AccordionGroup>
+
+## Data Management
+
+<AccordionGroup>
+<Accordion title="Is there a limit to how many records I can have?">
+There's no hard limit on record counts. However, very large datasets may impact performance in some views. Use filters and views to manage large datasets effectively.
+</Accordion>
+
+<Accordion title="Can I import data into custom objects?">
+Yes, you can import CSV data into any object, including custom objects. The import process supports field mapping for custom fields. See [How to Prepare Your CSV Files](/user-guide/data-migration/how-tos/prepare-your-csv-files).
+</Accordion>
+
+<Accordion title="Can I export my data model configuration?">
+Currently, there's no built-in export for data model configuration. Contact support if you need to migrate your data model between workspaces.
+</Accordion>
+
+<Accordion title="How many fields can a single object have?">
+The maximum number of fields a single object can have is 1600 fields as per Postgres limits, including both existing and deleted fields. Be aware that Twenty won't fix your workspace if the limit of 1600 fields is reached as it falls under our Fair Usage policy.
+</Accordion>
+</AccordionGroup>
+
+## Need More Help?
+
+Check our [Implementation Services](/user-guide/getting-started/capabilities/implementation-services) for help with complex data model design.

packages/twenty-docs/user-guide/data-model/overview.mdx

@@ -0,0 +1,166 @@
+---
+title: Data Model
+description: Learn what a data model is and how to design one that fits your business.
+---
+
+## What is a Data Model?
+
+A data model is the structure that defines how information is organized in your CRM. Think of it as the **blueprint** of your customer data — you design it once, then fill it with your actual data.
+
+## Key Concepts
+
+### Objects
+
+**Objects** are the main categories of data in your CRM. Each object represents a type of thing you want to track.
+
+Twenty comes with standard objects:
+- **People** — individuals (contacts, leads, partners)
+- **Companies** — organizations
+- **Opportunities** — deals or sales
+- **Notes** — notes attached to records
+- **Tasks** — to-dos linked to records
+
+You can also create **custom objects** for anything specific to your business (e.g., Projects, Subscriptions, Events).
+
+### Fields
+
+**Fields** are the properties or attributes that describe each object. They store the actual information.
+
+For example, the **People** object has fields like:
+- Name
+- Email
+- Phone
+- Job Title
+- Company (a relation to the Companies object)
+
+Fields have different **types**: text, number, date, select, multi-select, relation, and more. You can add custom fields to any object.
+
+### Records
+
+**Records** are the individual entries within an object — the actual data you create and manage.
+
+For example:
+- "John Smith" is a **record** in the People object
+- "Acme Corp" is a **record** in the Companies object
+
+**An analogy:**
+| Data Model Concept | Real-World Analogy |
+|-------------------|-------------------|
+| **Objects** | Sections in a book (the categories) |
+| **Fields** | Columns in a spreadsheet (the properties) |
+| **Records** | Rows in a spreadsheet (the actual entries) |
+
+You design the data model (objects + fields) once, then create many records within that structure.
+
+## Why Customize Your Data Model?
+
+Every business works differently. Customizing your data model means you can shape Twenty around **your** processes instead of forcing yours into a rigid system.
+
+Twenty offers full flexibility:
+- Create as many custom objects as you need
+- Add unlimited custom fields
+- The price doesn't change based on customization
+
+## Tips to Design Your Data Model
+
+### 1. Start with Your Core Objects
+
+Identify the main concepts you work with. Twenty already provides:
+- **People** — your contacts
+- **Companies** — your accounts
+- **Opportunities** — your deals
+
+Think about what else you might need:
+- Stripe would need a `Subscriptions` object
+- Airbnb would need a `Trips` object
+- An accelerator would need a `Batches` object
+
+### 2. Use Fields for Variations, Not New Objects
+
+If something is just a characteristic of an existing object, make it a **field**.
+
+**Use fields for:**
+- Categories and labels (e.g., `Industry` for Companies)
+- Status values (e.g., `Stage` for Opportunities)
+- Attributes and properties
+
+### 3. Create an Object When It Stands on Its Own
+
+If the concept has its own lifecycle, properties, or relationships, it deserves an object.
+
+**Create an object for:**
+- **Projects** — have deadlines, owners, and tasks
+- **Subscriptions** — connect companies, products, and invoices
+- **Events** — involve attendees and follow-up actions
+
+These go beyond a single field because they carry their own data and relationships.
+
+### 4. Create an Object When Records Are Open-Ended
+
+If something can be linked multiple times and you don't know how many, use an object.
+
+**Bad approach:**
+Creating fields like `Product 1`, `Product 2`, `Product 3`...
+
+**Good approach:**
+Create a `Products` object and relate it to records. This supports one, two, or a hundred products without changing your model.
+
+### 5. Keep It Simple First
+
+Start with fields. Move to new objects only when you feel the limits:
+- Too many fields on one object
+- Repeated records that should be separate
+- Relationships that don't fit neatly
+
+## Special Note on People, Companies, and Opportunities
+
+<Warning>
+**Email and calendar sync only works with People, Companies, and Opportunities.**
+
+These are the only objects where you can access synchronized emails and meetings from your mailbox/calendar. We recommend using them as much as possible.
+</Warning>
+
+**Best practices:**
+- If you need categories of People, use fields (not new objects)
+- Example: Use a `Person Type` field with values "Prospect" and "Partner" instead of creating separate objects
+- Create different **views** to filter: one showing partners, another showing prospects
+
+**It's okay to have fields that don't apply to every record.** For example, a `Referral Link` field on People that only applies when `Person Type = Partner`. Hide this field from views where it's not relevant.
+
+## Questions to Guide Your Choice
+
+Ask yourself:
+
+<Check>Is this just a property of something I already have, or does it need its own properties?</Check>
+<Check>Will I ever need to track multiple of these per record, without knowing how many?</Check>
+<Check>Does this concept connect to several different objects, not just one?</Check>
+<Check>Will it have its own lifecycle (stages, start/end dates)?</Check>
+
+If the answer is "yes" to one or more, it's probably time for a new object.
+
+## Accessing Your Data Model
+
+1. Go to **Settings** in the left sidebar
+2. Click **Data Model**
+3. View all your objects (standard and custom)
+4. Click any object to see and edit its fields
+
+<Note>
+**Don't see Data Model in Settings?**
+
+Access to the data model is usually restricted to administrators. Contact your workspace admin if you need access.
+</Note>
+
+## Next Steps
+
+Once you've planned your data model:
+
+- [How to Create Custom Objects](/user-guide/data-model/how-tos/create-custom-objects)
+- [How to Create Custom Fields](/user-guide/data-model/how-tos/create-custom-fields)
+- [How to Create Relation Fields](/user-guide/data-model/how-tos/create-relation-fields)
+
+## Need Help?
+
+<Tip>
+  Want help designing your data model? [Find a certified Twenty partner](https://twenty.com/partners/list?categories=SOLUTIONING&ref=docs-data-model) to design and build your objects, fields, and relationships.
+</Tip>