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

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.