mirror of
https://github.com/twentyhq/twenty
synced 2026-04-26 07:57:19 +00:00
161689be18
## Summary - **Fix junction relation toggle not being saved**: The form schema wasn't tracking the `settings` field, so changes to `junctionTargetFieldId` weren't marked as dirty - **Add type-safe documentation paths**: Generate TypeScript constants from `base-structure.json` to prevent broken documentation links - **Create many-to-many relations documentation**: Step-by-step guide for building many-to-many relations using junction objects - **Update `getDocumentationUrl`**: Now uses shared constants from `twenty-shared` for base URL, default path, and supported languages ## Key Changes ### Junction Toggle Fix - Added `settings` field to the form schema in `SettingsDataModelFieldRelationForm.tsx` - Fixed the toggle to properly merge settings when updating `junctionTargetFieldId` ### Type-Safe Documentation Paths - New constants in `twenty-shared/constants`: - `DOCUMENTATION_PATHS` - All 161 documentation paths as typed constants - `DOCUMENTATION_SUPPORTED_LANGUAGES` - 14 supported languages - `DOCUMENTATION_BASE_URL` / `DOCUMENTATION_DEFAULT_PATH` - Generator script: `yarn docs:generate-paths` - CI integration: Added to `docs-i18n-pull.yaml` workflow ### Documentation - New article: `/user-guide/data-model/how-tos/create-many-to-many-relations` - Updated `/user-guide/data-model/capabilities/relation-fields.mdx` with Lab warning and link ## Test plan - [ ] Verify junction toggle saves correctly when enabled/disabled - [ ] Verify documentation link opens correct localized page - [ ] Verify `yarn docs:generate-paths` regenerates paths correctly
90 lines
3.4 KiB
Text
90 lines
3.4 KiB
Text
---
|
|
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.
|
|
|
|
<img src="/images/user-guide/fields/junction-relation-diagram.png" style={{width:'100%'}}/>
|
|
|
|
<Warning>
|
|
**Lab Feature**: Junction relations must be enabled at **Settings → Updates → Lab** 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 **+ Add 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
|